MAXScript Online Reference

MAXScript is the built-in scripting language for 3ds max™ and related products, such as 3D Studio VIZ®, character studio®, and gmax™.

MAXScript provides users of these products with the ability to:

  • Script most aspects of the program's use, such as modeling, animation, materials, rendering, and so on.

  • Control the program interactively through the command-line Listener window.

  • Package scripts within custom Utility panel rollouts or modeless windows, to give them a standard user interface.

  • Package scripts as a macro, and install these macro scripts as buttons in the product's toolbars.

  • Extend or replace the user interface for objects, modifiers, materials, textures, render effects, and atmospheric effects.

  • Build scripted plug-ins for custom mesh objects, modifiers, and render effects.

  • Build custom import/export tools using the built-in file I/O.

  • Write procedural controllers that can access the entire state of the scene.

  • Build batch-processing tools, such as batch-rendering scripts.

  • Set up live interfaces to external systems through OLE Automation.

  • Record your actions in the product as MAXScript commands.

  • Store in scene files the scripts to run for each of the supported notification events, such as pre- and post-scene file open, new, reset, scene file save, pre- and post-render, selection change, and so on.

Note: Because the functionality of MAXScript is almost identical for 3ds max and the related products mentioned above, this reference refers to "3ds max" to avoid using product names redundantly. Where applicable, it also notes specific differences between MAXScript for 3ds max and 3DS VIZ. You must have a licensed copy of the other software product in order for the MAXScript functionality specific to that product to run as designed.

  • For extensions specific to 3D Studio VIZ, see topics under "MAXScript Extensions for 3D Studio VIZ" on the Contents tab.

  • For extensions specific to character studio 3, see topics under "MAXScript Extensions for character studio 3" on the Contents tab.

  • For a listing of MAXScript functionality included and excluded in the gmax software, see topics under "MAXScript and gmax" on the Contents tab. There are several non-game related globals, classes, methods, interfaces that are not supported in gmax. There are also additions that have been made to support the more game intensive features. Additionally, you will find several restrictions that have been placed on various aspects of MAXScript.

See also

MAXScript Overview

Tutorial: Learning MAXScript

What's New in MAXScript

The MAXScript Utility Panel

General MAXScript Topics

Syntax Definitions in This Document

Objects and Classes in Object-Oriented Programming

Using the MAXScript Documentation

MAXScript and gmax


MAXScript Overview

The MAXScript language is specifically designed to complement 3ds max. It has many special features and constructs such as coordinate system contexts, object primitives and materials that mirror high-level concepts in the 3ds max user-interface. It has an animation mode with automatic keyframing and access to scene objects using hierarchical path names that match the 3ds max object hierarchy.

The language syntax is simple enough for non-programmers, as it includes minimal punctuation and formatting rules. Coupled with the use of the command-line Listener window, the ability to install scripts as toolbar buttons, and the recording of user actions as MAXScript commands, MAXScript can be employed casually by the user while working in the 3ds max point-and-click user interface.

MAXScript is also rich enough to enable sophisticated programming tasks, with capabilities such as 3D vector, matrix, and quaternion algebra. MAXScript is well suited to working with large collections of objects; for example, making complex procedural selections, constructing random star fields, or placing objects in numerically precise patterns.

MAXScript allows scripts to be packaged as Utility panel rollouts, as modeless windows, and as 3ds max toolbar buttons. MAXScript can also be used to extend or replace the user interface for objects, modifiers, materials, textures, render effects, and atmospheric effects; or to create custom mesh objects, modifiers, and render effects. This allows job-specific tools to be scripted by the technical department and made available to artists and animators through standard 3ds max point-and-click user interfaces.

MAXScript supports formatted text I/O, so it is possible to produce asset reports directly from 3ds max scene files and read files containing scene layout, naming, texture details, and so on, exported from other project management software.

MAXScript can also be used as a high-level scene import utility. By outputting MAXScript scripts containing object creation commands, it is possible for other programs and packages to export directly using any of the high-level 3ds max constructs.


Using the MAXScript Documentation

This reference is written primarily for animators learning MAXScript. The topics are organized with the introductory material presented first, then descriptions of the MAXScript syntax and grammar, followed by a description of creating, accessing, and modifying the various 3ds max objects. These 3ds max objects include geometry objects, modifiers, controllers, materials, textures, and render effects. The MAXScript tools are then described, followed by descriptions of the methods for interacting with the 3ds max user interface, accessing external files, and establishing notifications to a script when an object or 3ds max state changes. Throughout these topics, the purpose and syntax of the commands in the MAXScript language are described.

Although it's helpful to have programming experience, the basic aspects of MAXScript do not require this or an in-depth understanding of the structure underlying 3ds max. Concepts presented in one topic do assume a basic understanding of the concepts presented in earlier topics. At the very least, the topics up to and including Controlling Program Flow should be read in order. By reading the topics in order, you will learn the MAXScript language starting with the basics, and work your way toward writing full-featured MAXScript utilities. In the later sections, features and techniques are presented for programmers with more advanced programming experience.

For those new to MAXScript, Learning MAXScript provides an introduction to the features, syntax, and practical applications of MAXScript.

For information about navigating this online reference, searching, and marking often-accessed topics, see topics in the last section, Using the HTML Help Viewer.

To see what has been added to MAXScript in 3ds max 4, see What's New in MAXScript.


Copyrights and Trademarks

Copyright © 2001 Autodesk, Inc.

All Rights Reserved

This publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose.

AUTODESK, INC. MAKES NO WARRANTY, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, REGARDING THESE MATERIALS AND MAKES SUCH MATERIALS AVAILABLE SOLELY ON AN "AS-IS" BASIS.

IN NO EVENT SHALL AUTODESK, INC. BE LIABLE TO ANYONE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH OR ARISING OUT OF PURCHASE OR USE OF THESE MATERIALS. THE SOLE AND EXCLUSIVE LIABILITY TO AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION, SHALL NOT EXCEED THE PURCHASE PRICE OF THE MATERIALS DESCRIBED HEREIN.

Autodesk, Inc. reserves the right to revise and improve its products as it sees fit. This publication describes the state of this product at the time of its publication, and may not reflect the product at all times in the future.

Autodesk Trademarks

The following are registered trademarks of Autodesk, Inc., in the USA and/or other countries: 3D Plan, 3D Props, 3D Studio, 3D Studio MAX, 3D Studio VIZ, 3DSurfer, ActiveShapes, ActiveShapes (logo), Actrix, ADE, ADI, Advanced Modeling Extension, AEC Authority (logo), AEC-X, AME, Animator Pro, Animator Studio, ATC, AUGI, AutoCAD, AutoCAD Data Extension, AutoCAD Development System, AutoCAD LT, AutoCAD Map, Autodesk, Autodesk Animator, Autodesk (logo), Autodesk MapGuide, Autodesk University, Autodesk View, Autodesk WalkThrough, Autodesk World, AutoLISP, AutoShade, AutoSketch, AutoSurf, AutoVision, Biped, bringing information down to earth, CAD Overlay, Character Studio, Design Companion, Design Your World, Design Your World (logo), Drafix, Education by Design, Generic, Generic 3D Drafting, Generic CADD, Generic Software, Geodyssey, Heidi, HOOPS, Hyperwire, Inside Track, Kinetix, MaterialSpec, Mechanical Desktop, Multimedia Explorer, NAAUG, ObjectARX, Office Series, Opus, PeopleTracker, Physique, Planix, Powered with Autodesk Technology, Powered with Autodesk Technology (logo), RadioRay, Rastation, Softdesk, Softdesk (logo), Solution 3000, Texture Universe, The AEC Authority, The Auto Architect, TinkerTech, VISION*, WHIP!, WHIP! (logo), Woodbourne, WorkCenter, and World-Creating Toolkit.

The following are trademarks of Autodesk, Inc., in the USA and/or other countries: 3D on the PC, 3ds max, ACAD, Advanced User Interface, AME Link, Animation Partner, Animation Player, Animation Pro Player, A Studio in Every Computer, ATLAST, Auto-Architect, AutoCAD Architectural Desktop, AutoCAD Architectural Desktop Learning Assistance, AutoCAD Learning Assistance, AutoCAD LT Learning Assistance, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk Animator Clips, Autodesk Animator Theatre, Autodesk Device Interface, Autodesk Inventor, Autodesk PhotoEDIT, Autodesk Software Developer's Kit, Autodesk Streamline, Autodesk View DwgX, AutoFlix, AutoSnap, AutoTrack, Built with ObjectARX (logo), ClearScale, Colour Warper, Combustion, Concept Studio, Content Explorer, cornerStone Toolkit, Dancing Baby (image), DesignCenter, Design Doctor, Designer's Toolkit, DesignProf, DesignServer, DWG Linking, DXF, Extending the Design Team, FLI, FLIC, GDX Driver, Generic 3D, gmax, gmax (logo), gmax ready (logo),Heads-up Design, Home Series, i-drop, Kinetix (logo), ObjectDBX, onscreen onair online, Ooga-Chaka, Photo Landscape, Photoscape, Plasma, Plugs and Sockets, PolarSnap, Pro Landscape, Reactor, Real-Time Roto, Render Queue, SchoolBox, Simply Smarter Diagramming, SketchTools, Sparks, Suddenly Everything Clicks, Supportdesk, The Dancing Baby, Transform Ideas Into Reality, Visual LISP, Visual Syllabus, VIZable, Volo, and Where Design Connects.

Discreet Logic Inc. Trademarks

The following are registered trademarks of Discreet Logic Inc., in the USA and/or Canada, and/or other countries: fire, flame, flint, flint RT, frost, glass, inferno, MountStone, riot, river, smoke, stone, stream, vapour, wire.

The following are trademarks of Discreet Logic Inc., in the USA, Canada, and/or other countries: backdraft, discreet, heatwave, jobnet, multi-master editing.

Third-Party Trademarks

All other brand names, product names, or trademarks belong to their respective holders.

Third-Party Software Program Credits

© 2000 Microsoft Corporation. All rights reserved.

Licensing Technology Copyright © Macrovision Corp. 1996-2001.

Portions Copyrighted © 2000 Intel Corporation.

Certain patents licensed from Viewpoint Corporation.

Portions developed by Lyric Media, Inc. for the exclusive use of Autodesk, Inc.

Portions of this software are based on the copyrighted work of the Independent JPEG Group.

Wise for Windows Installer © 2000 Wise Solutions, Inc. All rights reserved.

InstallShield™ Copyrighted © 2001 InstallShield Software Corporation. All rights reserved.

AnswerWorks® Copyright © 1997-2000 WexTech Systems, Inc. Portions of this software © Lernout & Hauspie, Inc. All rights reserved.

gmax contains Macromedia Flash™ Player software by Macromedia, Inc., Copyright © 1995-1999 Macromedia, Inc. All rights reserved. Macromedia and Flash are trademarks of Macromedia, Inc.

GOVERNMENT USE

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


The MAXScript Utility Panel

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

To access the MAXScript Utility panel rollout, open the Utilities panel and click the MAXScript Utility button.

The following options appear in the MAXScript rollout:

Open Listener

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

For Listener window features and commands, see The MAXScript Listener Window.

New Script

Opens a new MAXScript Editor window used for writing a new script. A new Editor window is also opened by choosing MAXScript > New Script in the 3ds max menu bar, or File > New Script in the Listener window menu bar.

For Editor window features and commands, see The MAXScript Editor Windows.

Open Script

Opens a common File Open dialog for choosing an existing script. A new MAXScript Editor window then displays the selected script. A script file can also be opened by choosing MAXScript > Open Script in the 3ds max menu bar, or File > Open Script in the Listener window menu bar.

For Editor window features and commands, see The MAXScript Editor Windows.

Run Script

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

For more information, see Running Scripts.

Utilities

Displays a list of available scripted utilities. A MAXScript defining a scripted utility must be executed before the scripted utility name appears in the Utilities list.

For more information, see Accessing Scripted Utilities.

Close

Closes the MAXScript Utility rollout. Any scripted Utilities panel rollouts are also closed.


The MAXScript Listener Window

The MAXScript Listener window is an interactive interpreter for the MAXScript language and works similar to a DOS command prompt window. You enter MAXScript commands in this window, and when you press ENTER they are executed immediately.

The Listener window is appropriate for performing interactive work and developing small code fragments. Extended blocks of code should be developed in a Script Editor Window.

Each command you execute in Listener is actually an expression with a result which Listener prints out after each execution. All commands in MAXScript are expressions or function calls that can look like commands in other languages. The terms command and expression are synonymous in MAXScript. You can enter any MAXScript expression or sub-expression in Listener for evaluation, and Listener prints out its result.

You can open only one instance of the MAXScript Listener window at a time. To open Listener, choose the MAXScript utility on the Utilities panel and click Open Listener. Other methods for opening Listener are described in The MAXScript Utility Panel.

The Listener window is a resizable, modeless window. You can switch between it and 3ds max as you work. If you close the Listener window and then reopen it, the text in the window before it was closed reappears. If Auto Open Listener on Output is checked in Customize > Preferences > MAXScript, the Listener window opens automatically when a script outputs to it.

Listener is divided into two panes: the top (pink) pane is the Macro Recorder pane, and the bottom (white) pane is the output pane. When the Macro Recorder is enabled, everything recorded is displayed in the Macro Recorder pane. The output of results from scripts are displayed in the output pane. The output of code executed in the Macro Recorder pane is always directed to the output pane so as not to clutter the recordings. Both panes allow you to cut-and-paste, drag-and-drop, edit, select, and execute code. You can resize the panes by dragging on the split bar between them.

On the left of the 3ds max status panel is a resizable Mini Listener. If the Mini Listener is not visible, drag on the vertical split bar at the left edge of the status panel to reveal the Mini Listener. The Mini Listener panes act as single-line sliding windows for the current line in the corresponding Listener panes. The Mini Listener panes always show what you are typing or where the edit cursor is placed in the Listener panes. Conversely, anything you type into a Mini Listener pane is entered into the corresponding Listener pane at the current edit cursor position.

You can install Listener into a 3ds max viewport by right-clicking the viewport label, choosing Extended, and then MAXScript Listener.

See also

Using the MAXScript Listener


Using the MAXScript Listener

The MAXScript Listener is a combination of text editor and command prompt window. MAXScript executes the commands you write when you press ENTER, but you can also scroll through the text to re-execute existing commands, or edit them and then have MAXScript execute the modified code.

Listener has the following features:

  • A line selection margin at the left window border. When you move the cursor into the left margin, it changes to a right-pointing arrow. A single-click selects an entire line, and click-dragging selects multiple lines.

  • Drag-and-drop for copying text within Listener and to and from script Editor windows.

  • Selected text is loaded automatically into the search text dialog field when you choose Search > Find or Search > Replace. This is useful for quickly finding other occurrences of the selected text.

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

Text Type | Variable | Default Color
typed input text | inputTextColor | black
output text | outputTextColor | blue
error message text | messageTextColor | red

For commands within the Listener window, see Listener Commands.

See also

Using the '?' Symbol

Turning on the Listener Log

Controlling the Listener Contents and the Insertion Point

Including Scripts Within Scripts

Aborting Execution with the ESC Key


Listener Commands

Menu Bar Commands and Keyboard Shortcuts

The following menu bar commands and keyboard shortcuts are available in Listener. The edit commands listed are also available in the Listener right-click menu. The menu bar commands for Macro Recorder are described in The Macro Recorder.

File > Save As, CTRL+S

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

File > New Script, CTRL+N

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

File > Open Script, CTRL+O

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

File > Run Script, CTRL+R

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

Edit > Undo, CTRL+Z

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

Edit > Cut, CTRL+X

Copies the selected text to the cut/paste buffer and deletes the text.

Edit > Copy, CTRL+C

Copies the selected text to the cut/paste buffer.

Edit > Paste, CTRL+V

Places the text in the cut/paste buffer at the cursor. If text is selected when executing this command, the selected text is replaced with the cut/paste buffer contents.

Edit > Delete, DEL

Deletes the selected text.

Edit > Clear All

Deletes all text in the active Listener pane.

Edit > Select All, CTRL+A

Selects all text in the active Listener pane.

Search > Find, CTRL+F

Displays Find dialog. Performs search in the active Listener pane for the Find What text. Search can be restricted to occurrences that are not part of a larger word, or are the exact combination of uppercase and lowercase letters as the Find What text. If matching text is found, the text is selected.

Search > Find Next, CTRL+G

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

Search > Replace, CTRL+H

Displays Replace dialog. Performs search in the active Listener pane for the Find What text, and replaces the matching text with the Replace With text. Search can be restricted to occurrences that are not part of a larger word, or are the exact combination of uppercase and lowercase letters is the specified text.

Help > Help

Displays the MAXScript Online Reference.

Help > About MAXScript

Displays About MAXScript dialog.

CTRL+B

Selects the text in the current bracket. Bracket balancer lets you check bracket balancing in long pieces of code. The balancer works with any of the following: (), [], and {}. To use it, place the cursor anywhere in the script text and press CTRL+B. If the cursor is next to a bracket, the code bracketed by it and its matching bracket will be selected and highlighted. If the cursor is not next to a bracket, the closest bracketed code containing the cursor will be selected. If you press CTRL+B again, the next outer bracketed fragment is selected, and so on. You can keep pressing CTRL+B to move out through bracket nestings. If at any point there is a bracket mismatch, the balancer will beep and not select any text.

End-Of-Text Commands

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

Editing and Executing Mid-Text Commands

When you want to use or edit existing text in Listener, you can differentiate between inserting new lines and executing the current line as follows:

  • Press ENTER to insert a new line at the current cursor position.

  • Press Number-Pad ENTER to execute the line that contains the cursor. When you reexecute an existing line, its output and any Error Messages are inserted after the current line if the output pane is active, or at the current edit cursor location in the output pane if the Macro Recorder pane is active.

If you do not have a number pad on your keyboard, SHIFT+ENTER is an alternative to the Number-Pad ENTER key.

Selecting and Executing Commands

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

Executing Code Blocks

MAXScript commands may be single or multiline commands, or Block Expressions. If you want to enter a block expression or a multiline command within existing text in the MAXScript Listener window, press ENTER to insert each line. Then drag-select all the lines in the command or block and press SHIFT+ENTER to execute the lines.

If you enter multiline commands or a block expression at the end of the text in the MAXScript Listener window, remember that each line is compiled when you press ENTER. The multiline command isn't executed until the end of the command is entered, nor are block expressions executed until the block is closed. While you cannot edit a faulty previous line within the multiline commands or block expression that has already been compiled but not yet executed, you can edit any text within the current line before you press ENTER. You can abort the current end-of-text compilation by pressing the ESC key to start over if necessary.

Installing Code Blocks as Macro Scripts

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


Using the '?' Symbol

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

x = ?

See also

Using the MAXScript Listener


Turning On the Listener Log

While you work in Listener, you can use the Listener logging feature to capture your entered text and all printed output into a text file. Only text entered in either pane and printed output to the output pane is captured. Macro Recorder output is not captured. You turn on logging with the openLog() method.

openLog <filename_string> [ mode: "w" | "a" ] [ outputOnly:<boolean> ]

where <filename_string> is a string literal or an expression that evaluates to a string, and specifies the name of the log file to be created. For example:

openLog "my_log.txt"

or

logfile="my_log.txt"

openLog logfile

The default mode (mode:"w") creates a new file or overwrites an existing file. To append the log results to an existing file; specify mode:"a". If the specified file does not exist, an error message will be generated. Both input and output are logged by default; specify outputOnly:true to log only MAXScript output. For example:

openLog "my_log.txt" mode:"a" outputOnly:true

would append only the MAXScript output to file my_log.txt.

If a log file is already open, the openlog() method will close that log file.

MAXScript echoes Listener activity as it occurs to the log file until you stop logging. The log file data is not continuously written to the file, rather the log data is written to a buffer in memory, and when the buffer is full the data in the buffer is written to the file. You can use the flushLog() method to ensure the log's buffer is flushed so that all output is written to the file:

flushLog()

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

closeLog()

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


Controlling the Listener Contents and the Insertion Point

The Listener output pane's content and insertion point placement can be controlled with the following methods:

clearListener()

Clears all text from the Listener output pane.

setListenerSel #(<start_integer>,<end_integer>)

Sets the current text selection in Listener. The start and end values are the character offsets in the Listener output pane text, starting at 0. If the start and end values are the same, no text is selected and the insertion point is placed at the specified point. You can specify -1 for the start or end values, which specifies the end of the Listener output pane text. For example, the following would put the insertion point at the end of the text:

setListenerSel #(-1,-1)

while the following would select all of the text in the Listener output pane text:

setListenerSel #(0,-1)

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

getListenerSel()

Returns the current text selection indexes as a two-element array, #(start, end). These values are the character offsets in the Listener output pane text, starting at 0. If there is no selection, but only an insertion point, the start and end values are equal. Only the selections set using the setListenerSel() method are recognized by this method. If no selection has been set using the setListenerSel() method, the start and end values returned are the offset to the end of the Listener output pane text.

getListenerSelText()

Returns the currently selected text, or an empty string if no text is selected and only the insertion point is showing. Only the selections set using the setListenerSel() method are recognized by this method. If no selection has been set using the setListenerSel() method, an empty string is returned. For example, the following lines would capture the entire contents of the Listener output pane to variable ListenerText:

( global ListenerText -- declare variable so its scope is higher

-- than inside just the following block

-- expression

( setListenerSel #(0,-1) -- select all the text

ListenerText=getListenerSelText() -- get selected text

setListenerSel #(-1,-1) -- set insertion point at

-- end of output pane

)

)

setListenerSelText <replacement_string>

Replaces the currently selected text with the replacement string. If no text is selected and only the insertion point is showing, setListenerSelText() inserts the replacement string at the insertion point. Only the selections set using the setListenerSel() method are recognized by this method. If no selection has been set using the setListenerSel() method, the insertion point is the end of the Listener output pane text. <replacement_string> is a string literal or an expression that evaluates to a string.

include <filename_string>

Inserts the specified file's content into the Listener output pane. The inserted text is not evaluated. You can use this method to load a script and then step through it, executing any selected text with SHIFT+ENTER. <filename_string> is a string literal or an expression that evaluates to a string, and specifies the name of the file to insert. Example uses are:

include "my_script.ms"

or

scriptfile="c:\\my_scripts\\my_script.ms"

include scriptfile

If you don't explicitly specify a directory in the file name, the file will be searched for in the following directories, in the order listed:

  • The current MAXScript directory

  • The 3ds max executable main directory

  • The Windows NT 32-bit system directory (system32)

  • The Windows 16-bit system directory (system)

  • The Windows directory

  • The directories that are listed in the PATH environment variable


The MAXScript Editor Windows

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

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

MAXScript Editor is suited to developing longer scripts or code fragments you want to keep. You can edit and test parts of them until they are complete, then save your code in a script file for later use. This is a common method for developing large scripts, utilities, and function libraries.

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

You can open a MAXScript Editor window from within the Listener or from other running scripts by calling the edit() method. The syntax for the edit() method is:

edit <filename_string>

where <filename_string> is a string literal or an expression that evaluates to a string, and specifies the name of the file whose contents are to be loaded into the new MAXScript Editor window. Example uses are:

edit "my_script.ms"

or

scriptfile="my_script.ms"

edit scriptfile

The file will be searched for in the following directories, in the order listed:

  • The current MAXScript directory

  • The 3ds max executable main directory

  • The Windows NT 32-bit system directory (system32)

  • The Windows 16-bit system directory (system)

  • The Windows directory

  • The directories that are listed in the PATH environment variable

You can create an empty MAXScript Editor window from within the Listener or from other running scripts by calling the newScript() method. The syntax for the newScript() method is:

newScript()

Opens an empty MAXScript Editor window and returns a WindowStream value that may be used as the target for print and format operations. This is useful for directing output to a separate window for ease of inspection or editing, or later saving to a file. Output to a WindowStream is inserted at the current cursor position in that window. For example:

debug = newScript()

...

print $foo to:debug

...

format "name is %\n" obj.name to:debug

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

showSource <fn>

A MAXScript Editor window has the following features:

  • Titles that display only the current script's file name, rather than its full path name, so minimized MAXScript Editor windows can be easily distinguished.

  • A line selection margin at the left window border. When you move the cursor into the left margin, it changes to a right-pointing arrow. A single-click selects an entire line, and click-dragging selects multiple lines.

  • Drag-and-drop for copying text to and from other MAXScript Editor windows, the Listener window, or any other text editor window that supports Window's drag-and-drop.

  • Selected text is loaded automatically into the search text dialog field when you choose Search > Find or Search > Replace. This is useful for quickly finding other occurrences of the selected text.

For commands use within the MAXScript Editor window, see MAXScript Editor Commands.


MAXScript Editor Commands

The following menu bar commands and keyboard shortcuts are available in the MAXScript Editor. The edit commands listed below are also available in the MAXScript Editor right-click menu.

File > New, CTRL+N

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

File > Open, CTRL+O

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

File > Close, CTRL+W

Saves the contents of the MAXScript Editor to the current file name, and then closes the Editor window. If there is not a current file name (that is, the MAXScript Editor window was opened with File > New), a common File Save dialog is opened.

File > Save, CTRL+S

Saves the contents of the MAXScript Editor to the current file name. If there is not a current file name (that is, the MAXScript Editor window was opened with File > New), a common File Save dialog is opened.

File > Save As

Opens a common File Save dialog for choosing a new file name used to store the existing script.

File > Evaluate All, CTRL+E

Evaluates the entire contents of the MAXScript Editor. This is similar to selecting all text, and then pressing SHIFT+ENTER. It has the advantage that the window's scroll position does not change.

Edit > Undo, CTRL+Z

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

Edit > Cut, CTRL+X

Copies the selected text to the cut/paste buffer and deletes the text.

Edit > Copy, CTRL+C

Copies the selected text to the cut/paste buffer.

Edit > Paste, CTRL+V

Places the text in the cut/paste buffer at the cursor. If text is selected when executing this command, the selected text is replaced with the cut/paste buffer contents.

Edit > Delete, DEL

Deletes the selected text.

Edit > Select All, CTRL+A

Selects all text in the MAXScript Editor.

Search > Find, CTRL+F

Displays Find dialog. Performs search in the MAXScript Editor for the Find What text. Search can be restricted to occurrences that are not part of a larger word, or are the exact combination of uppercase and lowercase letters as the Find What text. If matching text is found, the text is selected.

Search > Find Next, CTRL+G

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

Search > Replace, CTRL+H

Displays Replace dialog. Performs search in the MAXScript Editor for the Find What text, and replaces the matching text with the Replace With text. Search can be restricted to occurrences that are not part of a larger word, or are the exact combination of uppercase and lowercase letters in the specified text.

Help > Help

Displays the MAXScript Online Reference.

Help > About MAXScript

Displays About MAXScript dialog.

TAB, CTRL+I

Indents selected lines of text by one tab width.

SHIFT+TAB, SHIFT+CTRL+I

Unindents selected lines of text by one tab width.

SHIFT+ENTER

A MAXScript Editor can send code selections to Listener for evaluation. Select some text in MAXScript Editor and press SHIFT+ENTER to send the selected text to Listener. Listener compiles and evaluates it and prints out the result at the end of the current text in Listener. If you press SHIFT+ENTER with no text selected, the line containing the cursor is sent to Listener for evaluation. This behavior is similar to using SHIFT+ENTER in Listener, except that the results of the evaluations are printed in the Listener, not inserted into the MAXScript Editor text.

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

CTRL+Right-Click

Displays a pop-up menu of all the utility, structure, user-interface item, function, handler, plug-in, tool, Macro Script, and rcmenu definitions that exist in the current script. Select one of the items in the pop-up menu to position that definition at the top of the MAXScript Editor window. This simplifies large script navigation.

CTRL+B

Selects the text in the current bracket. Bracket balancer lets you check bracket balancing in long bits of code. The balancer works with any of the following: (), [], and {}. To use it, place the cursor anywhere in the script text and press CTRL+B. If the cursor is next to a bracket, the code bracketed by it and its matching bracket will be selected and highlighted. If the cursor is not next to a bracket, the closest bracketed code containing the cursor will be selected. If you press CTRL+B again, the next outer bracketed fragment is selected, and so on. You can keep pressing CTRL+B to move out through bracket nestings. If at any point there is a bracket mismatch, the balancer will beep and not select any text.

CTRL+D

Performs a simple syntax coloring scheme in the MAXScript Editor. Each time you press CTRL+D, the window is redrawn with comments in green, MAXScript reserved words in blue, and string literals in light red. This often helps in reading large, complex programs. New text is always colored black and you have to press CTRL+D at some point to recolor the script. Syntax coloring is a programming aid and does not effect script execution.

CTRL+R

Places the cursor at the location where it was previously placed with a mouse click or a find operation. Consecutive uses of CTRL+R cycle through the last eight cursor positions. This feature is useful if you edit at one location, move the cursor elsewhere with find or scroll operations, and then want to return to the edit location. This feature allows you to quickly review the code pieces you recently worked on.


Running Scripts

To run an existing script file, press Run Script on the MAXScript rollout, File > Run Script in the Listener menu bar, or MAXScript > Run Script in the 3ds max menu bar. This opens a common File Open dialog for choosing the script. MAXScript then reads and executes the selected script. Any output is printed to the Listener output pane.

You can also run a script from Listener or from within other scripts using the fileIn() method:

fileIn <filename_string> [ quiet:<boolean> ]

where <filename_string> is a string literal or an expression that evaluates to a string, and specifies the name of the script file whose content is executed. The script file content is executed one expression at a time, and halts processing if an error is encountered at any point. By default, the file is not listed as it is loaded; use quiet:false to get a running listing to the Listener. Example uses are:

fileIn "my_script.ms"

or

scriptfile="my_script.ms"

fileIn scriptfile

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


Accessing Scripted Utilities

The Utilities list in the MAXScript rollout contains scripted utilities that have been defined in startup scripts or while working in MAXScript. For details about defining scripted utilities, see Scripted Utility Panels.

As soon as you define a utility, MAXScript adds the utility's name to the Utilities list. When you select a utility from this list, its rollout is added to the Utilities panel after the MAXScript rollout. You can open as many utilities as you need, and close each one with its designated Close button.

If you modify and reexecute the script for an open utility rollout, that rollout is replaced immediately with the updated rollout. This lets you develop scripted utility rollouts incrementally with immediate, visual feedback.


The Macro Recorder

The MAXScript Macro Recorder captures many of the actions performed by the user, and generates the MAXScript commands that correspond to those actions. Output from Macro Recorder is displayed in the Macro Recorder pane of the MAXScript Listener window. Several filtering options are available that control what types of user actions are recorded, whether the generated MAXScript commands contain explicit object references or are selection-relative, and whether the generated MAXScript commands contain explicit or relative transforms and coordinates. These options are set using the MacroRecorder menu in the Listener window. The default option settings are specified in the MAXScript page of the 3ds max Preferences dialog, as described in the MAXScript Preferences Settings topic in the 3ds max User Reference. These settings can also be changed or set by editing the [MAXScript] section of the 3dsmax.ini file.

While many areas in 3ds max 4 generate Macro Recorder output, there are also many areas that do not. In general, most of the buttons on the 3ds max menu bar, toolbars, status bar, Create panel, and Modify panel will generate Macro Recorder output. If the button invokes a secondary dialog, changing setting or performing actions in the secondary dialog typically will not generate Macro Recorder output. In the Create and Modify panels, Macro Recorder output will be generated if the object or modifier can be created by MAXScript. In some cases, the plug-in implementing an object or modifier has not been updated to support Macro Recorder, so that object or modifier will not generate Macro Recorder output. Future versions of 3ds max and 3ds max plug-ins will be updated to support the Macro Recorder and will generate Macro Recorder output when used.

MAXScript supports text drag-and-drop onto toolbars to create Macro Script buttons. You can select and drag text from any text window, such as Listener window panes or Editor windows, onto any visible toolbar. The cursor changes to an arrow with a + sign when it is OK to drop the text. If you drop it, a Macro Script button is added to the toolbar with the dropped text as the body of the Macro Script. The classic case here would be to drag text from the Macro Recorder pane onto a toolbar to make a button that does the sequence of events just recorded. For more information, see Defining Macro Scripts.

The following Macro Recorder menu commands are available in Listener:

Enable

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

Explicit Scene Object Names/Selection-Relative Scene Object Names

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

move $Sphere03 [55.6739,23.5,0]

If Selection-Relative Scene Object Names is enabled, a typical generated command would be:

move $ [0,-47.8044,0]

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

Absolute Transform Assignments/Relative Transform Operations

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

$.position = [55.6739,23.5,0]

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

move $ [0,-47.8044,0]

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

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

Specifies whether to use explicit sub-object identifiers or the sub-object selection set property in the generated commands. For example, if Explicit Sub-object Sets is enabled, a typical generated command would be:

move $Sphere02.verts[#{20..32, 51..65}] [40.0986,10.3648,0]

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

move $Sphere02.selectedVerts [40.0986,10.3648,0]

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

Command Panel Switchings

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

Tool Selections

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

Menu Item Selections

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


General MAXScript Topics

This section presents topics that supply information on general MAXScript topics.

Error Messages

Aborting Execution with the ESC Key

MAXScript Desktop State

Startup Scripts

Running Scripts from the Command Line

The Scripts Included with 3ds max

Source Code Layout and Continuation Lines

Including Scripts within Scripts

Encrypting Script Files


Error Messages

When MAXScript detects a runtime error in your script, it displays an error message and prints diagnostic information to the Listener output pane. If the error occurs in a controller script or rollout panel script, the error message is displayed in an Alert Box window, otherwise it is printed in the Listener output pane.

The diagnostic information is in the form of a call stack trace-back which can help determine the cause and location of the error in your code. The call stack trace-back shows the nesting of called MAXScript functions at the point of error, deepest ones first to outermost ones last. The call stack trace-back also displays the values in all the local variables and function parameters at the levels they are declared or first used. Note that for loops produce separate entries in the call stack trace-back and include a variable dump for the loop variable and any locals in the loop body.

As a further aid in locating the error, MAXScript shows the line in which the error occurred in an MAXScript Editor window if the running code was compiled from a source file (any code not entered directly in the Listener). If the source file is not currently open in a window, MAXScript opens the file in a new MAXScript Editor window. The line containing the code in which the error occurred is highlighted and scrolled into view. The error message is either displayed in a Alert Box window or the Listener window. In both cases, the Alert Box or Listener window is brought to the front and the MAXScript Editor window containing the code causing the error is immediately behind.

All compile and runtime error messages reported in the Listener output pane are preceded by the comment symbol "--", so you can reselect and evaluate code in Listener that might have embedded error messages and not have them cause syntax errors.

In the following figure, an Editor and a Listener window are shown where an error was detected while running the script. The error occurred in the highlighted line in the Editor window. Looking at the call stack trace-back, we see the error occurred when the for loop variable i is equal to 6. In the line in error, the position of the object specified by the sixth element of array b is being set. After further investigation, it was found the array b only had five elements defined. Thus element b[i] contained the value undefined, which resulted in the error as there is no position property associated with undefined.

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


Aborting Execution with the ESC Key

You can abort running MAXScript code by pressing and holding the ESC key. MAXScript may take a moment to respond, so hold the ESC key down until it does. The ESC key aborts any currently executing MAXScript code, whether it is in a scripted utility, a script controller, or running in the MAXScript Listener window. If the MAXScript code that is aborted is in a script controller, a Script Controller dialog is displayed showing the script used by the controller. Execution of the script controller will restart when you click the Close button.

MAXScript code locks out the rest of 3ds max while it is executing. You cannot work interactively in 3ds max while MAXScript code is running to avoid conflicts between code actions and your actions. If 3ds max appears unresponsive at any time, it may be running MAXScript code which you can attempt to abort by pressing ESC. If you are testing scripts and 3ds max doesn't return control to you within a reasonable time, press ESC to abort the code execution. You can also press ESC to abort a compilation of a multiline command in the MAXScript Listener window.

Use the MAXScript global variable escapeEnable in scripts to turn on and off the ESC key interrupt detection.


MAXScript Desktop State

MAXScript remembers the state of its desktop (the location of active Editor and Listener windows) when you exit 3ds max and restores this state when you restart MAXScript. Any MAXScript Editor files missing when you restart will not have their windows reopened.

The desktop state is stored in a file called maxscrpt.dsk in the 3ds max executable directory. You can rename this file and replace it if you want to keep several desktop setups configured, or simply delete it so the current desktop will not be restored.


Startup Scripts

When the 3ds max is first started, MAXScript searches for any startup script files that it then automatically loads and runs. This feature is useful if you have function libraries you always use and want preloaded, or if you want to establish custom UI settings, define scripted plug-ins, or load scripted utility rollouts.

The automatic loading of startup script files can be deactivated by turning off the Auto Start MAXScript option in the MAXScript page of the Preferences dialog, as described in the MAXScript Preferences Settings topic in the main product online help.

MAXScript first searches for a file named startup.ms in the following directories, in the order listed:

  • The Scripts directory (defined in the Configure Paths dialog)

  • The Startup Scripts directory (defined in the Configure Paths dialog)

  • The 3DS executable main directory

  • The Windows NT 32-bit system directory (system32)

  • The Windows 16-bit system directory (system)

  • The Windows directory

  • The directories that are listed in the PATH environment variable

MAXScript stops searching when it finds the first occurrence of startup.ms.

MAXScript then recursively scans the plug-ins and Startup Scripts directories (both defined in the Configure Paths dialog) and directories nested within them for .ms and .mse script files and loads them. In this pass, any script files with the name startup.ms are ignored. This allows you to place your scripted plug-in scripts in the plug-in folders for automatic loading. They can be managed like DLL plug-ins, and used to organize your startup scripts into groups in their own directories for easier management. You can prevent a nested directory from being scanned by placing its name in parentheses, for example "(old-versions)", allowing you to enable and disable scripts in handy directory-based groupings.


Running Scripts from the Command Line

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

c:\3dsmax\3dsmax -U MAXScript rendercams.ms

This example command line would launch the 3ds max executable in c:\3dsmax, start MAXScript, and then have it run the launch script rendercams.ms.

The following example launch script loads two scenes, renders frames from each of the cameras in them, and then quits 3ds max:

loadMaxFile "foo.max"

for c in cameras do render camera:c outputfile:("foo_"+c.name+".bmp")

loadMaxFile "baz.max"

for c in cameras do render camera:c outputfile:("baz_"+c.name+".bmp")

quitMax #noPrompt

This example makes use of the quitMax() method to exit 3ds max (see Exiting and Resetting 3ds max ) when the script is finished. Launch scripts need not be batch scripts as in this example, but may be used to condition 3ds max for interactive use, for example by loading a scene file and setting some user-interface options.

The normal startup scripts, startup.ms and those in the Startup Scripts directory, are run before the launch script.

It is also possible to install scripts into individual scene files that run automatically when that scene is open or closed or at certain other events (see General Event Callback Mechanism).


Source Code Layout and Continuation Lines

The layout rules for MAXScript code are unlike those of most programming languages and give you the advantages of freeform languages, such as C and C++, but without the need for extensive punctuation, like semicolons and parenthesized parameter lists.

MAXScript lets you break statements and expressions across lines wherever you want, providing the line break is in the middle of an expression. MAXScript reads your code until the end of each line and determines whether it has a complete expression. If it does not, it continues to read subsequent lines until it finds the rest of the expression.

Take as an example the following line:

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

This line can be broken after any of the operators. MAXScript continues to read the next line, because an operator needs another argument. For example:

a + b * c / d - e +

f * g / h

You cannot break the example line as shown next and get the same result, because the expression on the first line is a complete expression. MAXScript considers the two lines as separate expressions, and the second line is now syntactically wrong, because it starts with an operator.

a + b * c / d - e

+ f * g / h

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

if a < b then print c else print d

or,

if a < b then print c

else print d

or,

if

a < b

then

print c

else

print d

If you do want to break a line at the end of a sub-expression, you can use the backslash line continuation character: '\'. The previous example above of an invalid break can be made valid using the line continuation character after the 'e':

a + b * c / d - e \

+ f * g / h

Whenever MAXScript encounters a '\' as the last character on a line, except for spaces, tabs, or comments, it continues to read the next line as though the line break were not present.

Line continuations are often used to break up function calls with many arguments, as shown in many of the Expressions topics.

MAXScript also lets you combine multiple statements and expressions in a single line. The statements or expressions are separated with a ';'.

Example:

print "End of input data reached" to:f ; close f ; f = undefined

if a < 0 do (print "value out of range";a=0)

Comments in MAXScript begin with a double-hyphen ('--') and extend to the end of the current line. Many code examples in this help file use comments in this style.

Example:

-- special cases...

if first do

subanims[6]=undefined -- subanims[6] is #Image_Motion_Blur_Multiplier


Including Scripts Within Scripts

MAXScript provides a compile-time source-file include mechanism, allowing you to break up large scripts into smaller files that can be included at nearly any point in a script. You can use the include <file> construct at any point in your code to effectively insert the contents of a file at that point in your code. The form is:

include "filename_string"

This is a compile-time construct, therefore the file name specification must be a string literal, and not a variable or an expression.

Example:

utility foo "Baz"

(

local a, b, c

include "foo-ui.ms"

rollout bar "Bar"

(

include "bar-rollout.ms"

)

include "foo-handlers.ms"

)

The include <file> construct is effectively replaced in the source code at that point with the contents of the named file.

You can nest included files as deeply as needed; included files can include other files, and so on.

Because include is a compile-time construct, the current MAXScript scope is maintained within the included file. This is opposed to the fileIn() method described in Running Scripts, whose script file content is compiled in a global scope context. For more information, see Scope_of_Variables.

The include <file> can appear at any point a new token is expected, such as a name, literal, or punctuation. This means that you could complete a partial expression with an included file. For example:

include "op1.ms" + include "op2.ms"

if include "test2.ms" then print a else print b

You cannot place an include <file> within a token. For example, the following is not valid:

timeval = 2:include "framenum.ms".0


Encrypting Script Files

MAXScript lets you create an encrypted copy of a specified script file with the same name prefix, but with the suffix .mse, in the same directory as the source script file. The encryption uses a fixed hidden key that lets it run on any 3ds max system, but effectively hides the source of the script. Encrypted script files have the suffix .mse. To encrypt a script, use the following MAXScript method:

encryptScript <filename_string>

where <filename_string> is a string literal or an expression that evaluates to a string, and specifies the name of the script file whose contents are encrypted. Example uses are:

encryptScript "my_script.ms"

or

scriptfile="my_script.ms"

encryptScript scriptfile

The encrypted script file from the previous examples would be named my_script.mse.

The Run Script button in the MAXScript rollout and the fileIn() method described in Running Scripts automatically support .mse encrypted scripts.

You can couple this script source code encryption with the hardwareLockID variable and the encrypted file I/O functions to provide authorization-based protection for your scripts.


Syntax Definitions in This Document

The ways you can write MAXScript tokens and clauses are given using a set of shorthand rules as shown in the following example:

[-]{<digit>}[.{<digit>}][(e | E)[+ | -]{<digit>}+]

These rules, or syntax definitions, follow the standard EBNF notation (Extended Backus-Naur Form).

The previous example shows the syntax for a decimal number in MAXScript. The rules typically contain a number of characters with special meanings. For example, brackets enclose optional items, such as the minus sign in front of the number. Braces enclose items you can use repeatedly, and bars separate multiple items from which you can choose one. Sometimes, rules are given names so they can be referred to in the documentation or as parts of other rules. The special characters in the rules have the following meaning:

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

(...|...|...) -- choose one of the items separated by the bars

{...} -- you can specify the braced item ZERO or more times

{...}+ -- you can specify the braced item ONE or more times

::= -- define a name for a syntax rule

<rule> -- you can insert what is defined by the named rule

bold_characters -- characters or token as written

The previous number syntax example is interpreted as follows:
Syntax | Definition
[-]{<digit>} | an optional minus sign (the sign), followed by 0 or more digits (the integer part), followed by
[.{<digit>}] | an optional sequence (the fraction part) comprised of: a period character, followed by 0 or more digits, followed by
[(e | E)[+ | -]{<digit>}+] | an optional sequence (the exponent part) comprised of: either an 'e' or 'E', followed by an optional plus or minus sign, followed by one or more digits.

Examples of valid numbers are:

123

1.456

-0.89e-7

1.536E23

The following numbers are not valid:

12x34

-0.45x10^3

0e

The syntax definitions in MAXScript Grammar are in the form of named rule definitions. For example:

number ::= [-]{<digit>}[.{<digit>}](e | E)[+ | -]{<digit>}+]

allowing the rule to be referred to by name in other rules in the grammar. An example of such a rule is:

mod <number1> <number2>

modulo arithmetic, the remainder when <number1> is divided by <number2>

Some definitions throughout this document also use the convention of showing alternative definitions for a rule on consecutive lines instead of separating them with the '|' symbol.


Objects and Classes in Object-Oriented Programming

To understand the terminology associated with MAXScript, a basic understanding of object-oriented programming is required.

All of the values you work with in MAXScript have a well-defined type, such as integer, matrix3, or twist. The type of a value is also known as its class, following the convention of modern object-oriented languages. We've been using a somewhat neutral convention so far of calling the things you compute with values. The term for these things in object-oriented languages is, not surprisingly, object. The terms object and value are synonymous in this document. An object is a particular instance of an class.

For example, in MAXScript Box is a class. It is not a box as shown in 3ds max, but rather defines the characteristics such a box has. These characteristics include the ways to create an instance of the Box class (a box object); the properties of a box object (such as Height, Width, and Length); and operations you can perform on a box object (such as move, copy, and delete). To create a box object, you would say:

b=box()

In this line box() is a constructor - it causes a box object to be created, and returns a reference to the box object. This reference is then stored in variable b. No parameters (such as Height, Width, and Length) were supplied for the constructor, so the default values specified by the Box class are used. In the 3ds max viewports, the box object is displayed, and can be manipulated like any other object you create in 3ds max. If parameters are supplied for the constructor, these parameters replace the "()". For example:

b=box width:10 length:100

creates a box object with the supplied parameters. All unsupplied parameters will use their default values.

MAXScript is internally object-oriented. All the built-in classes are arranged in an inheritance hierarchy and most of the built-in functions are polymorphic, terms we'll explore below. You cannot, however, create new classes in MAXScript and the functions you can script are not polymorphic. This may change in later versions of MAXScript, but it is an advanced refinement that is not really necessary in an application scripting language, where the most important abstractions are the features of the host application and are already built-in.

See also

Inheritance and Polymorphism

Properties, Methods, Operators, and Literals


Inheritance and Polymorphism

Inheritance and polymorphism are the two defining characteristics of object-oriented languages. Inheritance is the ability of an object class to inherit the operations and properties of its parent class. Polymorphism is the ability of a single-named operation to work on different values of different object classes. We'll explore them here to see how they are used in 3ds max and MAXScript.

First and foremost, both characteristics depend on the system having a well-defined type, or class, for every value. Assigning classes to values divides all the values you can work with into groups, each of which have well-defined operations and properties for their values. In some languages, like standard C++, the class is only manifest at compile-time. In others, like Smalltalk and MAXScript, the classes are actual runtime entities and every value has a runtime class-tag that says what class it is. This is the main reason MAXScript can have type-free variables. It can look at the class-tag of the value in a variable at runtime to determine its class.

Once the objects are grouped into classes, the groups themselves can be arranged into hierarchies. We do this all the time in real life. A classic example is the biological hierarchy, arranging real-life objects hierarchically into animals and plants and mammals and vertebrates and humans and adults and children, and so on. An object-oriented language provides a way to arrange value classes into hierarchies and, like the hierarchies we are used to, a class at some point in the hierarchy shares all the operations and properties of all its parent classes. This sharing is known as inheritance in object-oriented languages, and the operations and properties defined for a class are automatically inherited by all of its descendant classes. As an example, the following is the hierarchy for the Box class:

Value

MAXWrapper

Node

GeometryClass

Box

Various characteristics are defined for a class, and each lower class inherits those characteristics. For example, the classOf() method is defined for class Value, and class Box inherits this method through its hierarchy. Thus you can specify a Box object as a parameter to the classOf() method.

In the MAXScript Class Hierarchy topic, all the built-in classes in MAXScript are laid out in their place in the hierarchy so you can see for each class the classes it inherits characteristics from. Some of the hierarchy comes from within 3ds max itself which is internally object-oriented. All of its objects, modifiers, controllers, and so on are arranged in a well-defined inheritance hierarchy.

Once the objects have been grouped into classes, the symbology for the operations that can be performed on objects of each class can be simplified. The classic example of this comes from mathematics. The symbolic operators '+', '-', '*', and '/' are shared among many types of values (integers, reals, complex, vectors, matrices, and so on), and perform the correct action on the types they are applied to. This capability for a single-named operation to work on different types is called polymorphism. Object-oriented languages let you use the same name for different methods or operators across different classes, and the correct method to apply is automatically determined based on the class of the value it is used with.

In MAXScript, all math operators and methods are polymorphic in this sense and reflect the standard mathematical conventions. An interesting example for 3ds max use is the random() method. It takes two arguments and generates a random value between them. So, if you give it floats it gives you a float back; if you give it 3D points, it gives you a random point in the box they define the corners of; if you give it quaternions, it gives you back a random rotation between them, and so on.

Further, all the methods that work on 3ds max objects are polymorphic within their hierarchies. So move, hide, and select work on all types of scene objects; time scaling and insertion work on all the types of controllers, and so on.


Properties, Methods, Operators, and Literals

One principle of object-oriented programming is that how a class operates internally is hidden. All interactions with a class are defined by the external interfaces for the class. These external interfaces are broken up into several categories.

Properties: Accessible parameters for objects of the class. Examples of properties are height, width, and length for boxes, and radius for spheres.

Methods: Defines all the functions you can call for objects of the class. Examples of methods are moving or rotating a 3ds max object, adding a modifier to a 3ds max object, and accessing the position of vertices in a 3ds max object. The terms method and function are synonymous in this document.

Operators: Defines the math and other symbolic operators that are defined on values in the class. An example of an operator is the '-' operator, which will perform a mathematical operation on numbers, colors, vectors, and matrices, but will perform a Boolean subtraction when used with 3ds max objects.

Constructors: The various ways you can create objects of the class. For example Point3 0 0 0 and <color> as Point3 are constructors for the Point3 class. Executing either of these constructors will create a new Point3 object.

Literals: Any literal form for objects of the class. For example [0,0,0] is a literal form for the Point3 class, and "Hello world" is a literal form for the String class.


What's New in MAXScript

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

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

For design details, see the SDK help file topic, "Parameter Blocks and Maps in Release 3."

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

The scripter SDK allows extensions to be added either incrementally through a MAXScript-specific DLL file type that is loaded by MAXScript or by runtime calls directly to MAXScript from within an existing plug-in.

For design details, see the SDK help file topic, "MAXScript SDK."

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

The following topics are new to MAXScript:

  • Learning MAXScript - Walkthrough tutorial for beginning MAXScript users.

Additional Notes:

The name of the atmosphere in releases prior to 3ds max 4, known as the "Combustion effect" is now called "Fire_Effect".

The following deflectors have been renamed:

Pspawnflector is now POmniflect

Sspawnflector is now SOmniflect

Uspawnflector is now UOmniflect

Any scripts with these objects should be updated with the correct names.

The following are new MAXScript features in 3ds max 4:

Action Manager:

Action Manager

ActiveX Controls in MAXScript Rollouts:

ActiveX Controls in MAXScript Rollouts

Asset Browser:

Asset Browser enhancements

Bones:

Access to the new node bone properties and methods

Bone Creation

Cache Modifiers:

Point Cache Modifier

CallBack Notification Codes:

RenderEffect Progress Callback Mechanism - You can control the main RenderEffects dialog progress bar using several callbacks.

Notify Callbacks for Animate button on and off Transitions

Color Manager:

Interface: colorMan

Combustion:

Combustion

Constraints:

Path Constraint

LookAt Constraint

Orientation Constraint Controller

Position Constraint

Link Controller for Constraints

Controller Functions for use with Constraint Assignments

Context Filters:

Context Filters

Custom Attributes:

Scripted Custom Attributes

Depth of Field:

Depth of Field

Edit Mesh:

ApplyOperation function

Editable Patch:

Patches

Filters:

class id filter

Selection Filter

iDrop - drag and drop:

iDrop - drag and drop

Interfaces:

Interfaces

Core Interfaces

Other Interfaces

Inverse Kinematics:

HD IK controller chains can be assigned to existing hierarchies

IKLimb Solver

Materials:

Multi/Sub Material

Menu Manager:

Menu Manager

Mesher:

Mesher

Network Render Interface:

Network Render Interface

Node Handles:

Node Handles

Node vertexColorType:

Node vertexColorType

OLE Automation:

MAXScript.reg - Registery file

Parameter Wiring:

Parameter Wiring

Plug-In Manager:

Plug-In Manager

Portable Licence Manager:

maxOps

Quad Menu:

Quad Menu

Reactors:

Reactor controller

Render Elements Manager:

Render Element Manager

Scripted Plug-In:

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

Scripted Plug-in Events

Scripted Cameras:

Scripted Cameras

Scripted Controllers:

dependsOn For Scripted Controllers

Matrix3 Scripted Controller

Scripted Manipulators:

Scripted Manipulators

Scripted Objects:

on detachedFromNode For Object Scripted Plug-ins

Scripted RenderEffects:

RenderEffect Progress Callback Mechanism

Scripted Rollouts:

Multi-line editText UI items in Scripted Rollouts

Spring Controller:

Spring Controller

System Tools:

System Tools

TrackBar:

Trackbar Interface

Trackviews:

Trackviews

Visual MAXScript:

Visual MAXScript

Xref Objects:

Xref Objects

Zip-file Script Packages:

Zip-file Script Packages

MAXScript Language Improvements in 3ds max 4:

The following are new MAXScript methods for 3ds max 4:

IsValidNode

getTextExtent

isActive <atmos>

isActive <renderEffect>

affectRegionVal

getMAXSaveFileName & getMAXOpenFileName

Language Improvements:

Affect Region Function

BinStream for Binary Reading and Writing

By Reference Parameter Passing

C++-style bracketing comments

Coercion of bitArray to array and integer arrays to bitArrays

Detecting Deleted Nodes

Dereferencing Operator

forceUpdate Function added to UVWUnwrap

hasProperty() function

Improved the Performance of Iterating and Indexing the 'selection' and '$' Object Sets

isValidNode

Readable/Writable Checks

RubberBanding in pickObject() Function

SetDir

Shortcut system replaced

startObjectCreation()

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

superclasses read-only global variable

Symbolic Pathnames

System Information

validModifier() function

Visible Class For '&' Reference Values

Controllers:

List Controller

mapKeys() method

moveKeys function

Keys:

Bezier Keys inTangentLength and outTangentLength

Object Inspector Functions:

Class and Object Inspector Functions Enhanced

Renderer:

render() Function Re-entrant

SuperClasses:

Bitmap Manager - Function Published BMM control

Utilities, Global Utilities and Render Element plug-ins

Renderer

2 New Scripted Pug-in Superclasses

Globals and Locals:

Definition Constructs Can Include Global Variable Declarations At Top Level

Changes to Undeclared Implicit Global Variables

Material Editor, Material and Textures:

Accessing The Material Editor Active Slot

BitmapTex Reload and viewImage

BMP, PNG, JPEG and TGA I/O Interfaces

Material Editor Access

Material Level Show-in-viewport State

Maxops:

maxOps

User Interface:

Angle UI element

CreateDialog

Curve Control

isActive

keyboard.escPressed

MAX Open & Save Dialogs

Menu and CUI Loading

mtlBrowser

SetBackground Method

mouseTrack() Function

snapMode

Spinner UI Item setKeyBrackets

Timer UI element

TimeSlider on/off toggle

Undo/Redo Dropdown Labels

Zoom to Bounds

Command Panels and Rollout Pages:

Customize The Order of Rollup Pages

MAXScript Dialogs and Rollout Floaters as Extended viewports

Rollout .Controls Property

Rollout Systems 'category' Mechanism

All Const and MAXScript Functions in 3ds max 4:

MAXScriptFunction List

Const Class

Const Generic

Const MappedGeneric

Const NodeGeneric

Const Primitives

Const StructDef

New Classes in 3ds max 4:

New Classes in release 4

New MAXScript Interfaces in 3ds max 4:

Core Interfaces:

Core Interfaces

Other Interfaces:

Other Interfaces

The following topics contain updates to previous MAXScript documentation:

  • General Event Callback Mechanism - New notifications (everything from #systemPreReset down is new)

  • Defining Macro Scripts - Explanation of how the memory stack treats local macro script variables. (only need to review the one paragraph - "Normal locals are visible...")

  • Editable_Mesh : GeometryClass and TriMesh : Value - New MeshOps, including sub-object support.

  • New properties/methods in:

  • Skin

  • Flex

  • UVW Unwrap

  • Added/updated properties to the following objects/modifiers/controllers:

  • Attachment

  • Path

  • XYZ Controllers

  • Point Surf

  • Ringwave

  • Terrain

  • Point

  • Multimaterial (materialIDList, material1)

  • FFD_2x2x2 (deformType)

  • FFD_3x3x3 (deformType)

  • FFD_4x4x4 (deformType)

  • FFD_Box (deformType)

  • FFD_Cyl (deformType)

  • MeshSmooth

  • Blur

  • Deflector

  • Gravity

  • PDynaFlect

  • POmniFlect

  • SDeflector

  • SDynaFlect

  • SOmniFlect

  • UDeflector

  • UDynaFlect

  • UOmniFlect

  • Wind

  • Arc

  • Circle

  • Donut

  • CV_Curve

  • Ellipse

  • Helix

  • Line

  • NGon

  • Rectangle

  • Point_Curve

  • SplineShape

  • Star

  • Text

  • CompositeMaterial (amount, baseMaterial)

  • RaytraceMaterial (enable_Raytraced_refractions)

  • SpaceFFDBox (deformType)

  • SpaceFFDCyl (deformType)

  • StandardMaterial (bounce, staticFriction, slidingFriction, ambient, diffuse, specular, selfIllumAmount, selfIllumColor, specularLevel, glossiness, soften)


Action Manager

Topic: version 4 MAXScript New Features/ Action Manager

All Action Items are macro recorded when executed. This includes main menus items, CUI buttons, keyboard shortcuts and quad menu items.

The code emitted for many action items looks like:

actionMan.executeAction 0 "50002" -- Tools: Rotate Mode

The MAXScript Interface: actionMan Interface_BoneSyshas a function called "executeAction". It takes as parameters the ID of the action table and the "persistent id" of the action. A comment string that includes the category and tooltip for the action follows it. Some action items have custom code emitters that emit better looking code.

This interface is currently intended only for running macro recorded actions.

Note: There is no way currently to query the action manager for all the available action items.

actionMan.loadKeyboardFile "KbdFile.kbd"

This loads the named keyboard file from the current UI directory.

actionMan.saveKeyboardFile "KbdFile.kbd"

Saves the current keyboard configuration into the given file name in the UI directory.

actionMan.getKeyboardFile()

Returns the full path to the current keyboard file.

See also

Interface: actionMan

The Macro Recorder

Defining Macro Scripts

The MAXScript Listener Window

Turning On the Listener Log

Listener Commands


ActiveX Controls in MAXScript Rollouts

Topic: version 4 MAXScript New Features/ActiveX Controls in Rollouts

This feature expands the number of controls that can be created in MAXScript by allowing any type of ActiveX Controls to be embedded in a rollout.

Examples include:

Simple controls

ActiveMovieControl Object,

Calendar Control,

Microsoft TreeView

…

Compound controls

Microsoft Excel,

Microsoft Internet Explorer

Adobe Acrobat

…

This provides numerous possibilities in MAXScript which include:

  • Embed a web browser into a rollout and then navigate the user to a web site.

  • Embed an Excel spreadsheet into a rollout, extract the user entered values from cells and then create animation in Max.

  • Create an ActiveMovie player through MAXScript, load an Avi file and then synchronize the animation between the rendered Avi in ActiveMovie player to animation in Max.

The technology behind this feature is a MAXScript extension plug-in (MxsActiveX.dlx) making it MAXScript capable. It does not use ParamBlock2.

The plug-in adds a new type of rollout control. The syntax is:

activeXControl <name> [ <control_type> ] [ prop1:<value> ] [ prop2:<value> ] …

Parameters:

<control_type>

A string to create the control. The string must be formatted in one of the following ways:

  • A Program ID such as "MSCAL.Calendar.7"

  • A Class ID such as "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • A URL such as "http://www.microsoft.com"

  • A reference to an Active document such as "file://\\Documents\MyDoc.doc"

  • A fragment of HTML such as "MSHTML:<HTML><BODY>This is a line of text</BODY></HTML>"

    Note "MSHTML:" must precede the HTML fragment so that it is designated as being a MSHTML stream.

prop1:<value>

prop2:<value>

These are control specific keyword arguments. You can get a list of properties and their types by calling showProperties on the control.

Examples

activeXControl ax "{05589FA1-C356-11CE-BF01-00AA0055595A}" height:200 \

width:300 align:#left

Example

----------------------------------------------------------------------

-- Creates a Windows media player in a rollout.

-- Load an avi file by clicking the "Pick Avi" button and choosing an Avi file.

-- When the play button is hit the "on timer..." is called

-- This synchronizes the time slider with the active frame in the media player

-- Clicking show properties to get all the properties listed in the listbox

-- You can also set a property by picking a property from the listbox and entering the new value in the text below

--------------------------------------------------------------------

rollout rActiveX "Creates a Windows media player in a rollout"

(

local val

activeXControl ax "{05589FA1-C356-11CE-BF01-00AA0055595A}" height:200 width:300 align:#left

button btnPick "Pick Avi" pos:[320, 10]

button btnProps "Show Properties" pos:[320, 50]

listBox lbProps "Properties:" pos:[420, 10] width:170

editText etValue "Value:" pos:[385, 170] width:200

label lblStatus "" pos:[440, 190]

on btnPick pressed do

(

local f = getOpenFileName caption:"Pick Any Avi File" types:"*.avi"

if f != undefined then ax.FileName = f

)

on btnProps pressed do

(

showProperties ax

lbProps.items = getPropNames ax

)

on lbProps selected sel do

(

if lbProps.items.count > 0 then

(

try ( val = getProperty ax lbProps.items[sel] )

catch ( val == undefined )

etValue.text = val as string

)

)

on etValue entered text do

(

try( setProperty ax lbProps.selected (text as (classof val)) ) catch( etValue.text = "Set Failed" )

)

on ax timer do

(

sliderTime = animationRange.start + (ax.CurrentPosition * (animationRange.end - animationRange.start))/(ax.selectionEnd - ax.selectionStart)

)

on ax PositionChange oldPos newPos do

(

format "[%, %]\n" oldPos newPos

)

)

nf = newRolloutFloater "Test ActiveX" 650 300

addRollout rActiveX nf

Example

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

-------------------------------------------------------------------

-- creates a excel spreadsheet inside an embedded IE browser control

-- also registers it as an extended viewport

-------------------------------------------------------------------

rollout rExcel "Excel"

(

activeXControl ax "e:\\test.xls" height:250 width:370 align:#center

)

fExcel = newRolloutFloater "Excel" 390 270

addRollout rExcel fExcel

format "----Application----"

showProperties rExcel.ax.application

format "----Parent----"

showProperties rExcel.ax.parent

format "----Container----"

showProperties rExcel.ax.container

-- In case of MS Excel .document points to the msexcel.workbook

workbook = rExcel.ax.document

format "----Document----"

showProperties workbook showHidden:true

showMethods workbook showHidden:false

props = getPropNames workbook

sort props

for prop in props do

(

try

(

format "\t%=%\n" (prop as string) (getProperty workbook prop)

) catch ()

)

Properties

There are 2 common properties for ActiveX controls, .pos and .size. Other ActiveX properties are control specific and vary from one control to another.

Properties can be set like:

ax.filename = true

where ax is the control name.

Additionally, there is support for color properties. The internal representation of colors for ActiveX controls is COLORREF(unsigned integer) so you'll always get them in integers but you can set them as follows:

ax.forecolor = red -- if a .forecolor property exists

Methods

All methods of ActiveX controls are control specific and vary from one control to another. Methods can be called like:

ax.AboutBox()

ax.loadURL "www.discreet.com"

Events

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

Supporting Functions

showAllActiveXControls [ to:<stream> ]

Prints a list of ActiveX controls with their progID and classID, registered on your system.

showMethods <axControl> [ to:<stream> ] [showHidden:<false>]

Prints a list of methods and their arguments that can be invoked on the control

showEvents <axControl> [ to:<stream> ]

Prints a list of events and their arguments that are sent by the control

showProperties <axControl> [ to:<stream> ] [showHidden:<false>]

Prints a list of the properties and their types, supported by the control. Some properties are marked read-only

getPropNames <axControl> [showHidden:<false>]

Returns an array of the properties supported by the control

Common Parameters

to:<stream>

is the output stringstream.

showHidden:<boolean>

controls whether hidden properties/methods should be included in the enumeration. The default value is false.

All supported COM datatypes are converted to an appropriate MAXScript wrapper when passed to and from a COM object. Here are the supported types and their mapping:

undefined - VT_EMPTY

boolean - VT_BOOL

integer - VT_UI1

integer - VT_UI2

integer - VT_UI4

integer - VT_UI8

integer - VT_I1

integer - VT_I2

integer - VT_I4

integer - VT_I8

float - VT_R4

float - VT_R8

string - VT_BSTR

float - VT_CY

date - VT_DATE

error - VT_ERROR

color - VT_COLOR

MSDispatch - VT_DISPATCH

font - VT_FONT

undefined - VT_UNKNOWN

ComArray - VT_SAFEARRAY

ComArray - VT_CARRAY

ComArray - VT_ARRAY

Valid string handling for property sets and method call arguments, you can safely do

ax.Navigate "beta.discreet.com"

where: ax is the Microsoft Web Browser Control

Note

Restricted functions like QueryInterface, AddRef, Release are displayed by showMethods() function.

Example

---------------------------------------------------------

-- creates a IE browser control in a rollout as registers it an extended

-- viewport. Pick "Web Page" from the Extended Views

-- menu to display the rollout in the webpage. Also click various hypertext links

-- to see the text change in the viewports

---------------------------------------------------------

rollout rWebpage "Web page"

(

local txtObj

local vpsz = getViewSize()

activeXControl ax "www.yahoo.com" height:(vpsz.y-50) width:(vpsz.x-50) align:#center

fn checkTextObject =

(

if $text01 == undefined then

(

txtObj = text text:"" name:"text01"

addModifier txtObj (extrude amount:10)

txtObj.wirecolor = red

)

else ( txtObj = $text01 )

)

on rWebpage open do ( checkTextObject() )

on ax TitleChange txt do

(

checkTextObject()

if not (matchPattern txt pattern:"http:") then

(

if txtObj.text != text then

(

print txt

txtObj.text = txt

max tool zoomextents all

)

)

)

)

fWebPage = newRolloutFloater "Web page" rWebpage.vpsz.x rWebpage.vpsz.y

addRollout rWebPage fWebPage

registerViewWindow fWebPage

showProperties rWebpage.ax

Accessing Indexed Properties

getIndexedProperty <activeXControl : MSDispatch> <propName> <index>
setIndexedProperty <activeXControl : MSDispatch> <propname> <index> <value>

These functions are used to access properties on activeX controls that require an integer index.

Example:

getIndexedProperty s.ActiveSheet.Panes #item 1
setIndexedProperty s.ActiveSheet.Panes #item 1 "Subitem1"

Disable 3ds max keyboard accelerators

For most of the ActiveX controls there is no automatic way of determining if it supports keyboard input to disable Max's accelerators. Therefore a new MAXScript system global called "enableAccelerators" can be set to false whenever an ActiveX control gets focus so that the user can type in the controls.

Here is a sample that can be handy to enable/disable keyboard accelarators:

rollout rAccelState "State"

(

checkButton accelState "Test"

on rAccelState open do

(

accelState.text = if (enableAccelerators) then "Enabled" else "Disabled"

accelState.checked = enableAccelerators

)

on accelState changed state do

(

enableAccelerators = state

accelState.text = if (enableAccelerators) then "Enabled" else "Disabled"

)

)

nf = newRolloutFloater "" 100 100

addRollout rAccelState nf

Note: There is no real way of determing when an activeX control got focus and when it
lost it and automatically disable/enable Max's accelarators. It's upto the
script writer's discretion to find a clever way to disable them. There is a "on
StatusTextChange ..." event handler to disable the accelerators. Though it is not fail
proof.

on ax StatusTextChange txt do enableAccelerators = false

Shockwave flash object events

Here is a sample script that creates a text object and sets the text to FSCommand event argument value sent by shockwave flash objects:

rollout rFlash "Shockwave Flash Object"

(

local txtObj

fn checkTextObject =

(

if $text01 == undefined then

(

txtObj = text text:"" name:"text01"

addModifier txtObj (extrude amount:10)

txtObj.wirecolor = red

rotate txtObj 90 x_axis

)

else ( txtObj = $text01 )

)

activeXControl axFlash "{D27CDB6E-AE6D-11CF-96B8-444553540000}" height:200 width:300 align:#left

on axFlash OnReadyStateChange arg1 do format "handler: OnReadyStateChange : %\n" arg1

on axFlash OnProgress arg1 do format "handler: OnProgress : %\n" arg1

on axFlash FSCommand arg1 arg2 do

(

checkTextObject()

txtObj.text = arg1 + "+" + arg2

max tool zoomextents all

)

on rFlash open do

(

axFlash.movie = "e:\\Movie1.swf"

axFlash.movie = "e:\\Movie1.swf" -- need to load 2nd time sometimes

checkTextObject();

)

)

flashFloater = newRolloutFloater "Shockwave Flash Object" 350 300 10 10

addRollout rFlash flashFloater

COM enums are now represented as MAXScript name internals

Preforming a showProperties on Microsoft controls, like ListView, one of the properties returned is:

.MousePointer : MousePointerConstants( #ccDefault | #ccArrow | #ccCross | #ccIBeam | #ccIcon | #ccSize | #ccSizeNESW | #ccSizeNS | #ccSizeNWSE | #ccSizeEW | #ccUpArrow | #ccHourglass | #ccNoDrop | #ccArrowHourglass | #ccArrowQuestion | #ccSizeAll | #ccCustom )

which you can set like

ax.MousePointer = #ccArrow

Properties which return arrays can be iterated

For example, .listItems in the ListView control, returns IListItems. This can be looped through and also indexed.

for li in ax.listItems do li.bold = true

or

ax.listItems[1].text = "foo"

.description property

on any activeX control returns a description string of the format

<TypeLib name> (TypeLib info) ? <Help file name if any> - <help context id>

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

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

Example:

rollout controlR92 "Microsoft ListView Control, version 6.0"

(

activeXControl ax "{BDD1F04B-858B-11D1-B16A-00C0F0283628}" height:200 width:300 align:#left

--on ax Click do format "handler: Click\n"

--on ax DblClick do format "handler: DblClick\n"

on controlR92 open do

(

showProperties ax

ax.MousePointer = #ccArrow

ax.GridLines = true

ax.AllowColumnReorder = true

ax.BorderStyle = #ccFixedSingle

ax.view = #lvwReport

chs = ax.columnHeaders

--showProperties chs

--showMethods chs

hTargets = chs.Add()

hWeights = chs.Add()

hTargets.text = "Node"

hWeights.text = "Weights"

lis = ax.listItems

for i=0 to 10 do

(

local li

li = lis.Add()

li.text = "Item " + i as string

)

for li in ax.listItems do li.bold = true

li = ax.HitTest 100 1500

if li != undefined do

(

showProperties li

li.text = "Just Hit Tested"

showEvents controlR92.ax

showMethods controlR92.ax

)

)

)

nr92 = newRolloutFloater "Microsoft ListView Control, version 6.0" 350 300 10 10

addRollout ControlR92 nr92

See also

i-drop - drag and drop

Visual MAXScript

MAXScript Dialogs and Rollout Floaters as Extended viewports


Asset Browser enhancements

Topic: version 4 MAXScript New Features/Asset Browser

The Asset Browser provides access from your desktop to design content on the World Wide Web. From within the program you can browse the Internet for texture samples and product models. This includes bitmap textures (BMP, JPG, GIF, TIF, and TGA), or geometry files (MAX, DWG, and so on). You can drag these samples and models into your scene for immediate visualization and presentation. You can use the CTRL key to drag geometry into predefined locations. You can also use the Asset Browser to browse thumbnail displays of bitmap textures and geometry files on your hard disk or shared network drives. Then you can either view them or drag them into your sceneor into valid map buttons or slots.

  • Several special new icons are now used in Thumbnail view to represent script files (.ms, .mcr, .mse), dropScripts (.ds), and script zip packages (.mzp).

  • Now viewing or double-clicking script source files (.ms, .mcr, .ds) will open them in a MAXScript editor window, ready for editing and evaluation. You can also double-click .mzp script zip package files to open them in WinZip or some other zip utility if the type .mzp has been associated with that utility.

  • Executable script files (.ms, .mcr, .mse, .mzp) now have a Run... menu item available in the right-click menu on their thumbnail icons in the thumbnail view, allowing you to launch them directly from within the asset browser.

  • The home page for web views is now <max-directory>\web\maxindex.html.

Properties:

assetBrowser.open ()

Return Value:

Opens the asset browser if it is not already open.

Properties:

assetBrowser.gotoURL <URL_string>

<URL_string> - Opens the given URL in the asset browser.

Remarks:

This can be a web URL or a local or network disc directory path name.

See also

Interface: browserMgr

i-drop - drag and drop

Zip-file Script Packages


Access to the node bone properties and methods

Topic: version 4 MAXScript New Features/Bones

There are several properties and methods accessible on scene nodes that correspond to the Bone parameters and functions in the node properties dialog.

The new properties are:

<node>.boneEnable

boolean, read-only, see <node>.setBoneEnable for the set method.

<node>.boneAutoAlign

boolean

When turned off, the bone's pivot point will not align to its child object. The translation of a child bone will not be converted into rotation of the parent. Instead the child will be allowed to move away from the parent's X-axis.

Note

Changing the state of this check box will not have an immediate visual effect on the skeleton. It only affects future behavior when bones are moved. This option is only available if Bone is off.

<node>.boneFreezeLength

boolean

When turned on, the bone maintains its length. When turned off, the bone's length is based on the translation of its child bone. This option is available only if Auto-Align is on.

<node>.boneScaleType

one of #scale, #squash, or #none

None: No stretch takes place.

Scale: Lets the bone scale. The stretch happens along one axis.

Squash: Lets the bone squash. The bone gets fatter as it gets shorter, and thinner as it gets longer.

<node>.stretchTM

matrix3, read-only

The new methods are:

Methods

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

Sets the Bone enable on or off.

<onOff boolean>

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

<initial-time time>

Specifies the time at which to calculate and store initial child position. This is usually user with the current time slider position. The time associated with the time slider can be queried and set using the sliderTime global variable. Time Control

Note: A very good macroscript example to review, which uses .setBoneEnable, can be found in your 3ds max directory at: \ui\macroscripts\Macro_Bones.mcr.

<node>.realignBoneToChild ()

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

<node>.resetBoneStretch ()

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

See also

Node Common Properties, Operators, and Methods

Bone Creation

Bone : Helper

Skin : Modifier

Bones : System

Interface: BoneSys


Bone Creation

Topic: version 4 MAXScript New Features/Bones

Interface: BoneSys

There is a function published interface to create bone links.

Methods:

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

<startPosition>

The location of the new bone as point3

<endPosition>

The direction (X axis) of the bone and the bone length as point3

<zAxis>

The direction of the Z axis for the new bone node as point3

This 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

Core Interfaces

Node Common Properties, Operators, and Methods

Bone Creation

Bone : Helper

Skin : Modifier

Access to the New Node Bone Properties and Methods Bones_System


Point Cache Modifier

Topic: version 4 MAXScript New Features/Cache Modifiers/ Point Cache Modifier

Point_Cache - superclass: modifier

This is a simple point caching system. It lets you store modifier animation to a disk file that records only changes in vertex positions, and then play back the animation using the information in the disk file instead of the modifier keyframes. It caches the points of an object across time and then reads them from the disk on play back. It is useful when you have large intricate stacks that you want to speed up or modifiers such as flex that you want to bake.

This modifier sacrifices memory for speed, it stores 3 caches of the points to allow for fast reading from the disk. You can instance this modifier but the instances must have the same number of points, otherwise the results will be inconsistent. This also only record point position it does not store mapping, topology changes etc. It also cannot deal with animated topology changes.

4 MAXScript interface methods have been exposed to allow pressing the Record, Set Cache, EnableMods, and DisableMods buttons.

Methods:

<void>record()

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

<void>setCache()

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.

<void>enableMods()

Turns on all stack modifiers below the Point Cache modifier. Use this when you want to change modifier settings.

<void>disableMods()

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

WSM component of Point Cache.

PointCacheWSM interfaces:

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

See also

PointCache Interfaces

PointCache - superclass: modifier


Notify Callbacks for Animate button on and off Transitions

Topic: version 4 MAXScript New Features/CallBack Notification Codes

Notify callbacks for Animate button on and off transitions. The new codes for callback scripts are #animateOn and #animateOff.

See also

General Event Callback Mechanism


RenderEffect Progress Callback Mechanism

RenderEffects Progress Callback Mechanism

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

on apply <bitmap> progressCB: do <fn>

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

Methods

progressCB.setTitle <string>

Sets the title on the progress bar.

progressCB.progress <done> <total>

Indicates the progress of the rendering. Both arguments are integers; done indicates how much of the rendering has been completed, and total indicates how much there is to do.

When this is called, the main render effects progress bar is updated to reflect this progress. This function also returns a boolean, which if true indicates that the user has hit the escape key to cancel the effect rendering.

progressCB.check()

Indicates whether the user has hit the escape key to cancel the effect rendering. This function returns a boolean; false if processing should continue, and true if the user has cancelled the rendering.

Example:

on apply bm progressCB: do

(

…

progressCB.setTitle "My Effect Pass1"

…

escapeEnable = false -- turn on scripter escape processing

for i in …

(

<the effect rendering loop>

…

if progressCB.progress completed total then exit

)

…

escapeEnable = true

…

)

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

See also

RenderEffect : MAXWrapper

Scripted RenderEffect Plug-ins

Render Effects Common Properties, Operators, and Methods


General Event Callback Mechanism

MAXScript allows you to register callback scripts for all of the notification events supported by 3ds max, such as pre/post scene file open, new, reset, scene file save, pre/post render, selection change, etc. You can specify any number of callback scripts per notification event. Callback scripts can be bundled into ID'd sets, and can be deleted individually or all callback scripts in and ID'd set can be deleted. Callback scripts can be specified as persistent so that they are saved and loaded with the currently open file.

The callbacks are maintained by the following set of functions:

callbacks.addScript <callback_type_name> \ ( <script_string> | <script_stringstream> | \ fileName:<filename_string> ) \ [id:<name>] [ persistent:<boolean> ]

This method is used to register a new callback script. Requires as the first argument a name that specifies which type of notify event this script is associated with. The list of valid callback_type_name values is listed below.

The script is supplied either as a direct String or StringStream value containing the text of the script to run, or as a fileName: keyword argument, in which case the named file is loaded and run whenever the event notification callback occurs. You can specify either a direct string or a fileName:, but not both.

The optional id: parameter lets you tag one or a group of callbacks with a unique name so that you can remove them all as a group without interfering with other callbacks, perhaps registered by other scripted tools.

The optional persistent: parameter lets you control whether the script is saved permanently in the currently open scene file or is a global callback script that remains in place no matter what file opening and closing is performed. A true value for the parameter specifies that the script should be stored in the current file and loaded and registered for callback whenever that file is opened again. Persistent callback scripts are always removed when a new file is loaded or a reset is performed so that persistent scripts in one file don't accidentally get copied to a later file. The default for this parameter is false, indicating the script is a global script and is not persistent.

For example:

callbacks.addScript #preRender "setUpRenderGeom()" \ id:#jbwRender

registers a new callback script that will be called just before a render is performed. The script invokes a function (that has presumably already been set up). An unique ID has been assigned to the script for later selective removal.

callbacks.removeScripts [ <callback_type_name> ] [ id:<name> ]

This method is used to unregister and remove one or more callback scripts. Specifying just a callback event type name removes all the callback scripts for that event. Specifying just an id:<name> removes all callback scripts in all events with that ID. Specifying both limits the ID-based removal to the specified event type.

callbacks.show ()

This method lists out the current callback scripts in the Listener window.

callbacks.broadcastCallback <callback_type_name>

This method provides a way for you to simulate one of the events and have all the callback scripts for it executed. Within 3ds max, the #preRenderFrame and #preRenderFrame callbacks can only be called by the renderer. These callbacks can not be called by using this method.

The following is a list of valid callback event type names:

#unitsChange

Sent if the user changes the unit setting.

#timeunitsChange

Sent if the user changes the time format setting.

#viewportChange

Sent if the user changes the viewport layout.

#spacemodeChange

Sent if the user changes the reference coordinate system.

#modPanelSelChanged

Sent whenever the Modify panel opens on a new selection, either because the Modify panel was just selected or because a new selection is made in the scene. The notify occurs at a point just prior to panel redraw but after the selection has been established, so that callback functions can modify the panel state without it being overwritten.

System Notifications

#systemPreReset

Sent before 3ds max is reset.

#systemPostReset

Sent after 3ds max is reset.

#postSystemStartup

Sent when the software goes live.

#pluginLoaded

Sent whenever a plug-in is loaded.

#systemPreNew

Sent just before 3ds max is reset.

#systemPostNew

Sent just after 3ds max is reset.

#preSystemShutdown

Sent just before the software enters the shutdown process.

#postSystemShutdown

Sent just before the software finishes the shutdown process.

#colorChanged

Sent when the system is updating it's custom colors.

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.

#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.

#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.

#selectedNodesPreDelete

Sent just before selected nodes are deleted.

#selectedNodesPostDelete

Sent just after selected nodes are deleted.

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

#assetBrowserPreNavigate

Sent whenever a URL is loaded into the Asset Browser.

VIZ-Only Notifications

#heightMenuChanged

Sent when a user operated the height menu.

#fileLinkPreBind

Sent just before a file link bind.

#fileLinkPostBind

Sent just after a file link bind.

#fileLinkPreDetach

Sent just before a file link detach.

#fileLinkPostDetach

Sent just after a file link detach.

#fileLinkPreReload

Sent just before a file link reload.

#fileLinkPostReload

Sent just after a file link reload.

#fileLinkPreAttach

Sent just before a file link attach.

#fileLinkPostAttach

Sent just after a file link attach.

Other Notifications

#animateon

Sent when the Animate button is turned on.

#animateOff

Sent when the Animate button is turned off.

#mainWindowEnabled

Sent when main window gets enabled.

#selectionSetChanged

Sent after the selection set has changed.

#bitmapChanged

Sent after a bitmap is reloaded.


Interface: colorMan

This is an interface to the Color Manager. Within 3ds 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.

Note: After making any color changes, you must call 'colorMan.repaintUI #repaintAll' to apply the changes, and synchronize with the customize dialog.

useStandardWindowsColors()

Returns true if the standard windows colors are used and false if custom colors are used.

setUseStandardWindowsColors <boolean>onOff

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.

<boolean>onOff: Pass true to use the standard windows color and false to use the custom colors.

registerColor <string>color <string>name <string>category <point3 by value>defaultColor

This registers a new color with the system, and adds a color to the color manager database that is then accessible from the color customization UI. It returns false if the color is already registered; otherwise true.

<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 3ds 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 3ds max user presses "Reset" in the color customization dialog. Example: [1,0,0]

Example:

colorMan.registerColor #myNewColor "My Own Color" "Ugly Colors" [1,0,0]

This registers a new color, with the name #myNewColor, with a default value of red. The category in the customization UI will be "Ugly Colors" and the name will be "My Own Color".

In other scripts you can access this color using:

colorMan.getColor #myNewColor

Note: colorMan.registerColor should be called from a script in the \stdplugs\stdscripts folder. These scripts are run when 3ds max starts, so the color will be available in the customization UI immediately. If the user customizes this color, its value will be saved in the MaxColors.clr file.

loadColorFile <string>file

This method will load the specified color file from the current UI directory. Returns true if the load was successful, otherwise false.

Note: The path specified must be relative to the \UI directory.

<string>file: The filename of the color file to load.

saveColorFile <string>file

This method will save the specified color file from the current UI directory. Returns true if the save process was successful, otherwise false.

Note: The path specified must be relative to the \UI directory.

<string>file: The filename of the color file to save.

getColorFile()

Returns the file name of the current color file.

setColor <string>color <point3 by value>colorValue

Sets the color value of the previously registered color whose ID is passed. Returns true if the color was set and false if the id passed could not be found.

<string>color: Specifies which color to set.

<point3 by value>colorValue: The color value to set.

Predefined colors include:

#background -- The background for all controls and buttons

#text -- The text for all controls and buttons

#activeCommand -- The color command mode buttons turn when pressed

#hilight -- The hilight color for 3d controls

#shadow -- The shadow color for 3d controls

#window -- The background color for edit boxes, list boxes and other windows

#activeCaption --

#toolTipBackground -- The background for viewport tool tips

#toolTipText -- The text color for viewport tool tips

#hilightText -- The hilight color in the stack view drop-down list

#windowText -- The color used in edit boxes, list boxes and other windows

#itemHilight --

#subObjectColor -- The color used to hilight sub-object levels in StackView

#3dDarkShadow -- the dark shadow color on 3d controls

#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

getColor <string>color

Returns the color value of the color whose ID is passed, or black (RGB(0,0,0)) if the Color passed was not found.

<string>color: Specifies which color to get.

getName <string>color

Returns the name of the color whose ID is passed.

<string>color: The ID of the color.

getCategory <string>color

Returns the category string of the color whose ID is passed.

<string>color: The ID of the color.

setIconFolder <string>folder

<string>folder - The name of the folder relative to the UI directory. Absolute pathnames are not supported.

This method sets the folder from which all icons for the UI are loaded, and immediately reloads the icons from that folder.

Note: If a folder with no icon files is loaded, all icons in the UI become blank, and no warning is issued.

g etIconFolder()

Returns the absolute pathname of the current icon folder. Note that getIconFolder returns an absolute path while setIconFolder accepts only relative paths.

getIconColorScale <enum>type <enum>which

type enums: {#disabledIcon|#enabledIcon}

which enums: {#saturationScale|#valueScale|#alphaScale}

Returns a floating point value (in the range 0.0f to 1.0f) that is one of the scale factors applied to the specified icon type. These scale values used to do image processing on the icons at start-up time.

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

setIconColorScale <enum>type <enum>which <float>value

type enums: {#disabledIcon|#enabledIcon}

which enums: {#saturationScale|#valueScale|#alphaScale}

Sets the specified scale factor for the icon type passed. The color manager maintains the values for the 3ds 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.

<enum>type: The icon type. One of the following values:

#disabledIcon: The disabled icons.

#enabledIcon: The enabled icons.

<enum>which: The icon color scale. One of the following values:

#saturationScale: The saturation scale.

#valueScale: The value scale.

#alphaScale: The alpha scale.

<float>value: The value runs from 0.0 to 100.0.

getIconColorInvert <enum>type

type enums: {#disabledIcon|#enabledIcon}

Returns true if the invert flag is set for the specified icon type and false if not set.

<enum>type: The icon type. One of the following values:

#disabledIcon: The disabled icons.

#enabledIcon: The enabled icons.

setIconColorInvert <enum>type <boolean>value

type enums: {#disabledIcon|#enabledIcon}

Sets the invert flag for the specified icon type to on or off.

<enum>type: The icon type. One of the following values:

#disabledIcon: The disabled icons.

#enabledIcon: The enabled icons.

<boolean>value: Pass true for inverted; false for not inverted.

getFileName()

Returns the file name of the currently loaded color file.

Note: This filename specifies an absolute path, even though loadColorFile and saveColorFile use relative paths.

getDefaultColor <string>color

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.

<string>color: The ID of the color.

repaintUI <enum>type

type enums: {#repaintAll|#repaintTrackBar|#repaintTimeBar}

This method allows you to issue a repaint of the user interface. This is equivalent to the Apply Colors Now button in the Customize dialog.

<repaintType>type: The type of repaint you wish to issue; #repaintAll, #repaintTrackBar, #repaintTimeBar.

Here is a macroScript that turns the time slider and trackbar backgrounds blue:

Example:

macroScript BlueBar

category: "Color"

tooltip: "Blue Bar"

(

on execute do

(

colorMan.setColor #timeSliderBg [0, 0, .6]

colorMan.repaintUI #repaintTimeBar

colorMan.setColor #trackbarBg [0, 0, .6]

colorMan.repaintUI #repaintTrackBar

)

)

Note: All of 3ds max's standard icon BMP files must exist in that folder. If any of the standard files are missing, icons will appear blank in 3ds max's UI. All the icons files needed live in the UI\Icons folder, which is the default icon folder.

See also Class IcolorManager, in the SDK Help file accompanying this product


Combustion

Topic: version 4 MAXScript New Features/ Combustion

With the Combustion map, you can create maps interactively using the Discreet combustion product and 3ds max at the same time. You use combustion software to paint on a bitmap, and the material updates automatically in the 3ds max Material Editor and in shaded viewports.

Important: The combustion map works only if Discreet combustion is installed on your system.

You can use combustion as a material map in 3ds max. With a Combustion map, you can create a material from a Paint or composite operator, and in turn apply that material to objects in a 3ds max scene. The Combustion map can include combustion effects, and it can be animated.

In addition, with combustion you can import 3ds max scenes that have been rendered to a rich pixel file (RPF or RLA file). The imported rich pixel rendering becomes an element of your composite. You can adjust its 3D position relative to video elements of the composite, and you can apply combustion 3D Post effects to objects within it. See the combustion User's Guide for more information.

Note: Because 3ds max runs only on Windows, you cannot use combustion to create material maps on a Macintosh.

Note: The environmental atmospheric effect known as "Combustion" in versions prior to 3ds max 4 is now known as the Fire_effect.

A Combustion map is a 2D map. It is a combustion project used by the 3ds max Material Editor, so like any combustion project, it is vector-based, animatable, and fully editable. From within the Material Editor, you can have combustion create a new project from scratch, or use an existing composite or Paint branch. You can synchronize the combustion Timeline with the 3ds max time slider so animated materials synchronize with your 3D scene.

A macroScript has been added that gets called by the render management system to output render element info to the combustion(tm) .cws file format.

../UI/MacroScripts/Macro_CombustionOutput.mcr

Associated files include:

RenderElements-fns.ms

CombustionExport-fns.ms

Example:

C = combustion()

See also

Combustion.coordinates - superclass: MAXObject

Render Element Manager

Material Common Properties, Operators, and Methods


Path Constraint

Topic: version 4 MAXScript New Features/Constraints

Path_Constraint - superclass: PositionController

Path_Constraint Interfaces

A path constraint restricts an objects movement along a spline or at an averaged distance between multiple splines.

Path Target Object

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

See also

Path Interfaces

LookAt Constraint

Orientation Constraint Controller

Link Controller for Constraints

Controller Functions for Use with Constraint Assignments


LookAt Constraint

Topic: version 4 MAXScript New Features/Constraints

LookAt_Constraint - superclass: RotationController

LookAt_Constraint interfaces::LookAt_Constraint_interfaces_

Look-At Constraint constrains an object's orientation so that it's always looking at another object.

Note: The old Look At Controller, which is a full transform controller, will be invisible to the user unless an old file is loaded. The new LookAt Constraint Controller is a rotation controller and NOT a TM controller which the old LookAt was. The old LookAt will be phased out.

At this time, old LookAt.IsPublic returns zero, so that the users won't see the old LookAt. However, the old MAX files will still load the old LookAt and the camera and the light will continue to use the old LookAt.

See also

Path Constraint

Position Constraint

Orientation Constraint Controller

Link Controller for Constraints

Controller Functions for Use with Constraint Assignments


Orientation Constraint Controller

Topic: version 4 MAXScript New Features/Constraints

Orientation_Constraint - superclass: RotationController

Orientation_Constraint interfaces:

An Orientation Constraint causes an object's orientation to follow the orientation of an object or averaged orientation of several objects.

An Orientation Constrained object can be any type of object that inherits its rotation from a target object. Once constrained you can not rotate the object manually. You may move or scale the object as long as its not constrained in a manner that affects the object's position or scale controller.

The target object can be any type of object. The rotation of a target object drives the constrained object. Targets can be animated using any of the standard translation, rotation, scale tools.

See also

Path Constraint

Position Constraint

LookAt Constraint

Link Controller for Constraints

Controller Functions for Use with Constraint Assignments


Position Constraint

Topic: version 4 MAXScript New Features/Constraints

Position_Constraint - superclass: PositionController

Position_Constraint Interfaces

A position constraint causes an object to follow the position of an object or the averaged position of several objects.

In order to activate, a position constraint requires an object and a target object. Once assigned the object becomes constrained to the target objects position. Animating the target's position causes the constrained object to follow

Each target has a weight value defining its influence. A value of 0 is equal to off. Any value greater than 0 will cause the target to influence the constrained object. Weight values may be animated to create effects such a ball being picked up from a table.

Multiple targets can be used to influence a constrained object. When using multiple targets, each target's weight value defines how much it influences the constrained object. For example if a sphere is Position constrained between 2 targets and each target's weight value is 100. Then the sphere will maintain an equal distance between both targets even when they are in motion. If one of the weight values is 0 and the other is 50, then the Sphere is only influenced by the target with the higher value.

Example:

posCtrl = Position_Constraint()

posConstraintInterface = posCtrl.constraints

appendTarget <node>

Adds a node to the node list with a default weight of 50

getNode <index>

Returns the node specified by the index. Index is a 1 based array

getWeight <index> <time>

Returns the weight at the time for the node specified by the index.

setWeight <weight> <index> <time>

Sets the weight for the node specified by the index at the given time.

Use:

posConstraintInterface.appendNode $box01

posConstraintInterface.appendWeightedNode $box02 200

node1 = posConstraintInterface.getNode 1

posConstraintInterface.setNode $box03 2

weight = posConstraintInterface.getWeight 1 50

posConstraintInterface.setWeight 250 1 0

See also

Path Constraint

LookAt Constraint

Orientation Constraint Controller

Link Controller for Constraints

Controller Functions for Use with Constraint Assignments


Link Controller for Constraints

Topic: version 4 MAXScript New Features/Constraints

A Link constraint is used to animate an object linking from one target object to another.

The Link constraint causes an object to inherit the position, rotation and scale of its target object.

See also

Path Constraint

LookAt Constraint

Position Constraint

Orientation Constraint Controller

Link Controller for Constraints

Controller Functions for Use with Constraint Assignments


Controller Functions for use with Constraint Assignments

Topic: version 4 MAXScript New Features/Constraints

These functions are defined in in stdplugs\stdscripts\ControllerFunctions.ms
and in ui\macroscripts\ Macro_Constraints.mcr.

Methods

AddListController OBJ Trans ListType

Checks to see if a list controller is assigned. If not, it will assign to the designated Trans using the ListType, This way it can be used for all list controllers.

AddConstraint OBJ Trans Constraint List

SetActiveController OBJ Trans Controller

AddConstraintTargets OBJ Trans Array Target

Example:

Foo = Selection as array

AddListController "Foo[1]" "Pos" "Position_List"

See also

Path Constraint

LookAt Constraint

Position Constraint

Orientation Constraint Controller


Context Filters

Topic: version 4 MAXScript New Features/Context Filters

Filter functions for context-sensitive menus.

Use this for .IsEnabled or .IsVisible handlers in macrocripts. isEnabled and isChecked handlers have been added to many of the existingmacroScripts. All of the modifier, creation and polygon toolbox macroScripts have these two handlers.

These handlers allow object creation CUI buttons to turn green while creating objects, and modifier buttons are only enabled if they apply to the current selection. The polygon toolbox buttons also only enable when applicable, and the selection level buttons stay pressed while in the sub-object level.

This structure is defined in .\stdplugs\stdscripts\FilterFunctions.ms.

An example use of the filter functions can be found in the Selection and Display Callbacks Script File, .\stdplugs\stdscripts\Selection_Display_Filters.ms

#Struct:Filters(

Is_EditMesh:<fn>,

Is_NURBS:<fn>,

Is_EditPoly:<fn>,

Is_EditPatch:<fn>,

Is_EditSpline:<fn>,

Is_MeshSelect:<fn>,

Is_PolySelect:<fn>,

Is_SplineSelect:<fn>,

Is_PatchSelect:<fn>,

Is_PosXYZ:<fn>,

Is_RotationXYZ:<fn>,

Is_ScaleXYZ:<fn>,

is_Child:<fn>,

This is used for the new IK assignments.

is_Parent:<fn>,

This is used for the new IK assignments.

CanSwitchTo_XXXX for SubObject levels:

CanSwitchTo_Vertex:<fn>,

CanSwitchTo_Edge:<fn>,

CanSwitchTo_Face:<fn>,

CanSwitchTo_Polygon:<fn>,

CanSwitchTo_Element:<fn>,

CanSwitchTo_Border:<fn>,

CanSwitchTo_Patch:<fn>,

CanSwitchTo_Segment:<fn>,

CanSwitchTo_Spline:<fn>,

These can be used to check if MeshSelect, PatchSelect, SplineSelect, Edit(able) Patch, Edit(able)Mesh, and Edit(able)Spline can go into these subobject levels.

Are_Modifiers_Applied:<fn>,

The following requires a node to be passed into the function:

Is_Bone:<fn>,

Is_IKChain:<fn>,

Is_Point:<fn>,

Is_Light:<fn>,

Is_Camera:<fn>)

These return true if the selected object's function name condition is met.

See also

Macro Scripts

Defining Macro Scripts

macros const StructDef


Scripted Custom Attributes

Topic: version 4 MAXScript New Features/Custom Attributes

Custom Attributes let you create and assign additional parameters to any object, modifier, or material in your scene. This is useful for game and other project-specific data.

MAXScript provides a way to define and add these custom attributes to objects in the scene and also a way to define UI rollups for accessing these attributes.

Attributes can be added to an object via an "attribute definition". This is a new syntactic construct in MAXScript that is similar to a scripted plug-in definition, but rather than adding a new plug-in class, a definition is built that can be used to add custom attributes and rollup UI to any number of objects at any time, through a special new function.

Note:

You cannot use Custom Attributes for per-face-data. The face-data channels store objects of a user defined type and the scripter cannot create objects of types other than those known by MAXScript.

The new syntax has the following form:

attributes <varname> [version:n] [silentErrors:t/f] [initialRollupState:0xnnnnn]

(

<locals>

<globals>

<parameters>

<rollouts>

<handlers>

)

Remarks

The name is now simply a descriptive name for the definition and can be either a <name> or a <string>.

Example:

attributes "Game Data"

(

...

)

or

attributes gameData

(

...

)

The attribute header keyword parameters and main clauses are basically identical to the same keyword parameters and clauses in Scripted Plug-ins. The 'custom attributes' are effectively the parameters defined in any parameter clauses in the body of the attributes definition. The UI for them is defined by the rollout clauses, which will be automatically displayed in the Command Panel and Material Editor when an object containing custom attributes is selected.

Example:

attributes weaponData

(

parameters main rollout:params

(

hitPoints type:#float ui:hits default:10

cost type:#float ui:cost default:100

sound type:#string

)

rollout params "Weapon Parameters"

(

spinner hits "Hit Points" type:#float

spinner cost "Cost" type:#float

dropdownlist sound_dd "Sound" items:#("boom", "sparkle", "zap", "fizzle")

on sound_dd selected i do sound = sound_dd.items[i]

)

)

Remarks:

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

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

Adding Attributes to an Object

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

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

#unique

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

Note: If you extract the uniquely-added definition, and use it directly in another non-unique custAttributes.add() on some other object, a definition sharing will be set up. Using #unique when adding a global definition will make the added custom attributes non-global, they will have their own private definition which starts out being identical to the original global definition.

Example:

custAttributes.add $weapon01 weaponData

Opening $weapon01 in the Modify panel will now display the "Weapon Parameters" rollout and allow them to be edited as can normal object parameters. You can use attribute definitions to add their defined sets of attributes to any object at any time. Any appropriate type of parameter can be animated, also, exactly as with scripted plug-ins.

The custAttributes.add() function can be applied to an object collection to add sets of attributes to a group of objects in one go.

Example:

custAttributes.add $weapon* weaponData

Adds a separate set of these custom attributes to all objects whose names begin "weapon" in the scene.

Note: Further, an object can have any number of separate sets of custom attributes added from different attribute definitions.

As with Scripted plug-ins, an attributes definition can have any number of sets of parameter and rollout clauses, to allow you to organize added attributes into multiple rollouts as needed.

Scripted custom attributes added to an object or modifier can be accessed in MAXScript. They turn up directly as properties on the objects they are added to. If the names of any of the custom attributes are the same as existing properties on the host object, the custom attributes are effectively hidden when accessed directly. As an alternative, you can access each added block of custom attributes by their attributes definition name and then access individual attributes as properties within that block.

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

the_weaponData = attributes weaponData

(

parameters main rollout:params

(

hitPoints type:#float ui:hits default:10

cost type:#float ui:cost default:100

sound type:#string

)

rollout params "Weapon Parameters"

( ... )

)

the custom attributes could be accessed as

$box01.hitPoints

$box01.cost

$box01.sound

or indirectly through the attributes block:

$box01.weaponData.hitPoints

$box01.weaponData.cost

$box01.weaponData.sound

  • scripted custom attributes are properly saved to and loaded from scene files.

  • you can assign a fixed, global definition ID to an attributes definition.

This acts in a similar way to class IDs in scripted plug-ins. Such definitions are global across any number of scenes that custom attributes may be present in and all instances of custom attributes of a global definition will have the same shape. The ID is specified with a new header parameter, 'attribID:'

attributes <name>

attribID:#(<number>, <number>)

(

...

)

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

genClassID()

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

Global and Private Definitions

Definitions are identified now depending on whether they are global or private definitions. Global definitions have explicit attribID: parameters, which define a globally unique ID for that definition and ensure that any object with custom attributes based on a definition with that ID will be follow the same definition. Whenever you evaluate an attributes definition with a particular attribID: you will update all objects that have custom attributes based on that definition, and loading objects with attributes of that attribID will update themselves to the current definition.

Private definitions have no explicit attribID: parameter (they effectively have an internally-generated random one). Each time you evaluate one, except as described in the redefinition section below, a completely distinct definition is created with its own internal ID.

In the case of both global and private definitions, the 'attributes' definition construct now returns the definition as its value, so you would typically assign that value to a local and then use it to add custom attributes to objects via the custAttributes.add() function.

Example:

local def

def = attributes "Game Data"

(

parameters ...

rollout ...

)

custAttributes.add $box01 def

custAttributes.add $box02 def

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

Example:

attributes "Game Data"

redefine:def

(

parameters ...

rollout ...

)

This expects an existing attributes definition as the value given in the redefine: parameter and will update it to the definition that follows, and update any custom attributes made from that particular definition value. In the example, this would update $box01 and $box02.

Alternatively, you can use the new custAttributes.redefine method:

custAttributes.redefine <def> <definition_string>

Example:

local new_def = "attributes \"Game Data\" ( ... )"

custAttributes.redefine def new_def

This is particularly useful in situations where you are generating the attributes definition automatically as a string. You can use this function to compile and apply the redefinition to a particular definition object in one go, without having to construct a name for the object, as you would if you used the redefine: parameter scheme.

To redefine the attributes on some object, say based on the defData in that object's custom attributes, you might use this sequence:

old_def = custAttributes.getDef $box03 1 -- get existing def

old_def_data = custAttributes.getDefData old_def -- get my defData from it

new_def_string = generate_new_def old_def_data ... -- make new def string

custAttributes.redefine old_def new_def_string -- redefine it

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

Custom Attribute Management Functions

custAttributes.count <obj>

Returns a count of the number of separate scripted custom attribute sets have been added via the .add() function.

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

Returns the custom attribute set, specified as an index or by its defining attribute definition.

Note: The custom attribute set values, returned by the custAttributes. are effectively holder values for the object's custom parameters in that attribute set. You can get at these parameter values as simple properties on the attribute set value.

Example:

gp = custAttributes.get $ gameParams

gp.hitPoints = 50

This is equivalent to accessing the custom attribute parameters directly on the object:

$.gameParams.hitPoints = 50

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

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

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

If some objects with custom attribute sets share a specific attributes definition, you can make selected objects have unique copies of the definition.

Example:

custAttributes.add $box* def1

You can make box01 unique with:

custAttributes.makeUnique $box01 def1

or all of them unique with:

custAttributes.makeUnique $box* def1

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

Returns the attribute definition for a given custom attribute set in an object or from a custom attribute set accessed with the .get() method.

custAttributes.getDefs <obj>

Returns an array of definitions in attribute set order.

Attribute definition values

Attribute definition values now have several properties directly accessible:

<def>.name

Get and set descriptive name

<def>.source

Read-only, the source code for the definition

<def>.defData

Get and set the user-supplied def data value

<def>.attribID

Read-only, a two-element array containing the attribID for the def

custAttributes.getDefSource <attrib_def>

Returns the source code for the attributes definition as a string.

custAttributes.setDefData <def> <data>

Adds user-supplied data to an attributes definition.

The <data> value supplied here will be stored persistently with the definition and loaded on scene loads containing attribute sets of this definition.

custAttributes.getDefData <attrib_def>

Returns the saved user-supplied data.

custAttributes.getPBlockDefs <attrib_def>

These methods return an array containing a runtime readable encoding of all of the parameter block definitions in the custAttributes definition. The array is presented in the following form:

#(<paramblock>, <paramblock2>, ...)

<paramblock>

An array of details for one parameter block in this form:

#(<name>, <id>, <refno>, <keyword_params>, <parameter1>, <parameter2>, <parameter3>, ....)

<id>

The parameter block's internal ID number

<refno>

The reference number of the parameter block in the owning plug-in instance

<keyword_params>

An array of the keyword parameters given on the parameter block definition in the form:

#(<keyword>, <value>, <keyword2_name>, <value2>, ...)

<Parameter1 to ParameterN

Definition details for each parameter in the block in the following form:

#(<param_name> <keyword_params>)

<keyword_params>

An array containing all of the keyword parameters specified on that parameter's definition in the cust attrib definition, in the same form as the <keyword_params> above.

Example:

Here is a function that will extract pBlock data from a custom attribute.

mapped fn custAttribute_showPBlockDefs obj =

(

format "%\n" obj.name

for objDef in (custAttributes.getDefs obj) do

(

format "\t%\n" objDef

format "\tname: %\n" objDef.name

format "\tattribute id: %\n" objDef.attribID

format "\tParameter Blocks:"

pbArray = custAttributes.getPBlockDefs objdef

for a = 1 to pbArray.count do

(

itms = pbArray[a]

format "\n\t\tname = %\n" itms[1]

format "\t\tid = %\n" itms[2]

format "\t\towners reference number = %\n" itms[3]

keywordParams = itms[4]

format "\t\tparameter block keywords:\n"

for x = 1 to keywordParams.Count/2 do

(

format "\t\t\t% = %\n" keywordParams[x] keywordParams[x+1]

x = x+1

)

format "\t\tparameters:"

for y = 5 to itms.Count do

(

format "\n\t\t\t#name = %\n" itms[y][1]

for z = 1 to itms[y][2].Count by 2 do

(

format "\t\t\t% = %\n" itms[y][2][z] itms[y][2][z+1]

)

)

)

)

)

custAttributes.getSceneDefs ()

Returns an array of all the attribute definitions in the current scene.

custAttributes.deleteDef <attrib_def>

Deletes the given attribute definiton from the current scene and the current running MAX session. There must be no objects in the scene containing custom attributes added using this definition.

Note: The name can be obtained via the .name property.

Materials and Texture Maps

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

Note:

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

See also

custAttributes const StructDef


Depth of Field

Topic: version 4 MAXScript New Features/

Depth of field is available for any renderer plug-in via a published function publishing interface. No ui has been added. Functionality can be tested by enabling various parameters via MAXScript, and performing a normal render.

The settable dof parameters can be seen by typing 'apropos "dof"' in the MAXScript listener window or here.

To create a DOF display in a camera viewport, simply call

maxops.DisplayActiveCameraViewWithMultiPassEffect

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

See also

DOF const StructDef

Depth_of_Field : RenderEffect

Interface: maxOps


ApplyOperation function

Topic: version 4 MAXScript New Features/Edit Mesh

The ApplyOperation function is used by the Quad menu for activating object functions.

fn ApplyOperation ctype oper =

(

If (Modpanel.getcurrentObject () == $.baseobject) then oper $

If Classof (Modpanel.getcurrentObject ()) == ctype then

(

oper $.modifiers[modPanel.getModifierIndex $

Modpanel.getcurrentObject ()]

)

)

Example:

This example starts the extrude function on EditMesh if it is either the currently selected modifier or baseobject.

ApplyOperation Edit_Mesh meshops.StartExtrude

See also

Quad Menu

MAXScriptFunction List


Patches

Topic: version 4 MAXScript New Features/Editable Patch

There is a patch function package containing a large number of functions for creating, modifying and accessing patch objects. The sub-object selection system in MAXScript has also been extended to cover patch objects.

  • The Editable Patch object in MAX was called 'Patch' in MAXScript. It has been renamed to 'Editable_Patch' to be consistent with Editable_Mesh and Editable_Poly, and to allow the new patch function package to be named 'patch'.

  • The MAXScript sub-object selection system has been extended to work with Editable Patch objects. This means that all the MAXScript VertexSelection, FaceSelection, and EdgeSelection properties and operations now work with patch objects. The 'face' sub-object selections in this system correspond to the 'patch' sub-object level when applied to patches.

  • The Patch functions. All the functions in this package take either a scene node containing an Editable Patch object or an Editable Patch base object as the first argument. QuadPatch and TriPatch objects need to be converted to Editable Patches for the Patch functions to be applicable. For example, when using the convertTo $foo Editable_Patch.

  • To create a patch object from scratch, create an Editable_Patch scene object to create an empty patch object and use the geometry & topology creations functions below to fill the patch out, then use the patch.update() function to complete construction.

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

Functions:

The following functions are used to get and set the overall geometry of the patch. Supply keep:true to the setNumXXX functions for them to retain existing vertex/vector/patch/edge data, defaults to false, which cleans out the geometry.

The functions are largely direct calls to the methods of the same name on the MAX SDK class PatchMesh. See the SDK Help file Advanced Topic "Working with Patches", and the documentation for the main Patch system classes for more detailed info.

<integer> patch.getNumVerts <obj>

patch.setNumVerts <obj> <num> [keep:<boolean>]

<integer> patch.getNumVecs <obj>

patch.setNumVecs <obj> <num> [keep:<boolean>]

<integer> patch.getNumPatches <obj>

patch.setNumPatches <obj> <num> [keep:<boolean>]

<integer> patch.getNumEdges <obj>

patch.setNumEdges <obj> <num> [keep:<boolean>]

The following functions get and set individual vertex and vector handle locations. The vertex and vector coordinates are interpreted in MAXScript's current working coordinate context.

Note: Consistent with the rest of MAXScript, all vertex/patch/vector/edge indexes start numbering at 1.

<point3> patch.getVert <obj> <index>

patch.setVert <obj> <index> <point3>

<point3> patch.getVec <obj> <index>

patch.setVec <obj> <index> <point3>

The following two functions are the main mechanism for creating individual patches in the patch mesh:

patch.makeQuadPatch <obj> <index> <va> <vab> <vba> <vb> <vbc> <vcb> <vc> <vcd> <vdc> <vd> <vda> <vad> <i1> <i2> <i3> <i4> <sm>

where:

index = The index of the patch to create (0> = index < numPatches).

va = The first vertex.

vab = Vector ab.

vba = Vector ba.

vb = The second vertex.

vbc = Vector bc.

vcb = Vector cb.

vc = The third vertex.

vcd = Vector cd.

vdc = Vector dc.

vd = The fourth vertex.

vda = Vector da.

vad = Vector ad.

i1 = Interior 1.

i2 = Interior 2.

i3 = Interior 3.

i4 = Interior 4.

sm = The smoothing group mask

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

where:

index = The index of the patch to create (0> = index < numPatches).

va = The first vertex.

vab = Vector ab.

vba = Vector ba.

vb = The second vertex.

vbc = Vector bc.

vcb = Vector cb.

vc = The third vertex.

vca = Vector ca.

vac = Vector ac.

i1 = Interior 1.

i2 = Interior 2.

i3 = Interior 3.

sm = The smoothing group mask

The following function forces all the geometry and topology caches to be rebuilt, change notifications to be sent and a screen redraw request to be flagged.

You must call this function after making any changes to a path object before exiting the script making the changes otherwise and invalid patch may bepassed to MAX possibly causing a crash. The patch.update() function is similar in function and purpose to the update() function in mesh object scripting.

patch.update <obj>

The following functions give access to the topology of an existing patch object. They return either indexes or arrays of indexes of the sub-objects requested.

Example:

getVertVecs() returns an array of the vectors coming out of the specified vertex.

<integer_array> patch.getVertVecs <obj> <index>

<integer_array> patch.getVertPatches <obj> <index>

<integer_array> patch.getVertEdges <obj> <index>

<integer> patch.getVecVert <obj> <index>

<integer_array> patch.getVecPatches <obj> <index>

<integer> patch.getEdgeVert1 <obj> <index>

<integer> patch.getEdgeVert2 <obj> <index>

<integer> patch.getEdgeVec12 <obj> <index>

<integer> patch.getEdgeVec21 <obj> <index>

The following functions access and manipulate the texture mapping information in the patch object:

patch.setNumMaps <obj> <num> [keep:<bool>]

<integer> patch.getNumMaps <obj>

patch.setMapSupport <obj> <map_chan> [init:<boolean>]

<boolean> patch.getMapSupport <obj> <map_chan>

patch.maxMapChannels <obj>

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

<integer> patch.getNumMapVerts <obj> <map_index>

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

<point3> patch.getMapVert <obj> <map_chan> <index>

patch.setMapVert <obj> <map_chan> <index> <point3>

<index_array> patch.getMapPatch <obj> <map_chan> <index>

patch.setMapPatch <obj> <map_chan> <index> <index_array>

The following functions get and set the material ID for the patch object as a whole or for individual patches:

<integer> patch.getMtlID <obj>

patch.setMtlID <obj> <mtl_id>

<integer> patch.getPatchMtlID <obj> <index>

patch.setPatchMtlID <obj> <patch_index> <mtl_id>

The following functions access and control viewport and renderer tessellation and visibility:

patch.setMeshSteps <obj> <steps>

patch.getMeshSteps <obj>

patch.setMeshStepsRender <obj> <steps>

patch.getMeshStepsRender <obj>

patch.setShowInterior <obj> <bool>

patch.getShowInterior <obj>

patch.setAdaptive <obj> <bool>

patch.getAdaptive <obj>

The following functions access topology info for the specified sub-object:

<integer_array> patch.getEdges <obj> <v1> [<v2>]

<integer_array> patch.getPatches <obj> <v1> [<v2>]

<integer_array> patch.getVectors <obj> <vert>

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

patch.transform <obj> <matrix3>

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

patch.weldVerts <obj> <threshold> <weldIdentical_bool> <startVert>

patch.weld2Verts <obj> <v1> <v2>

patch.weldEdges <obj>

patch.deletePatchParts <obj> <del_vert_bitarray> <del_patches_bitarray>

patch.clonePatchParts <obj> <patch_bit_array>

patch.subdivideEdges <obj> <propagate>

patch.subdividePatches <obj> <propagate>

patch.addTriPatch <obj>

patch.addQuadPatch <obj>

The following functions get and manipulate surface normal information. Again, normal vectors are given in MAXScript's current working coordinate context.

patch.patchNormal <obj> <patch>

patch.edgeNormal <obj> <edge>

patch.updatePatchNormals <obj>

patch.flipPatchNormal <obj> <patch>

patch.unifyNormals <obj>

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

The following functions access and change the vertex and interior vertex types:

patch.changeVertType <obj> <vert> #corner|#coplanar

patch.getVertType <obj> <vert> -> #corner or #coplanar

patch.changePatchInteriorType <obj> <patch> #automatic|#manual

patch.getPatchInteriorType <obj> <patch> -> #automatic or #manual

The following function returns the current mesh tessellation for the patch object:

<mesh value> patch.getMesh <obj>

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

<point3> patch.interpTriPatch <obj> <patch> <u> <v> <w>

<point3> patch.interpQuadPatch <obj> <patch> <u> <v>

SubObject Selection

The following methods require a selection to operate on. Using them with out selection will give no results.

subDivideEdges:

Quadpatch lengthsegs:1 widthsegs:1 length:100 width:100 isSelected:on

convertTo $ Editable_Patch

$.selectededges = #{1}

patch.subdivideEdges $ false

patch.update $

subdividePatches:

Quadpatch lengthsegs:1 widthsegs:1 length:100 width:100 isSelected:on

convertTo $ Editable_Patch

$.selectedfaces = #{1}

patch.subdividePatches $ false

patch.update $

addTriPatch/addQuadPatch:

Quadpatch lengthsegs:1 widthsegs:1 length:100 width:100 isSelected:on

convertTo $ Editable_Patch

$.selectededges = #{1}

patch.addTriPatch $

patch.update $

$.selectededges = #{3}

patch.addQuadPatch $

patch.update $

See also

patch const StructDef

patchOps const StructDef

Patch_Select - superclass: modifier

Patch : GeometryClass


class id filter

Topic: version 4 MAXScript New Features/Filters

In the Selection filters/combos filter you can, in addition to registering super classid filters, add class id filters. The bottom left list box displays a list of all helper and geom class ids. To add a filter select one and hit the add button below the list box. It will then appear in the lower right list box. This list displays all of the current class id filters. Once OK is pressed then the select filter drop down contains those class ids that were added.

You can also register filters through a callback in MAXScript.

fn selectfilter_cb node =

(

print currentTime

true

)

registerSelectFilterCallback selectfilter_cb "MAXScript"

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

Methods

registerSelectFilterCallback <filterFunction> <name>

<filterFunction>

The filter function

<name>

The string which appears in the filter drop down list

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

Prototype:

unregisterSelectFilterCallback <filterFunction>

<filterFunction>

The filter function

There is also an unregisterSelectFilterCallback which removes the callback.

Example:

unregisterSelectFilterCallback selectfilter_cb

See also

Selection Filter

Main Toolbar

toolMode const StructDef


Selection Filter

Topic: version 4 MAXScript Language Improvements /User Interface

The Selection Filter list lets you restrict to specific types and combinations of objects that can be selected by the selection tools. For example, if Cameras is selected, you can select only cameras with the selection tools. Other objects do not respond.

<int>GetSelectFilter

Returns your current selected select filter in the toolbar.

<void >SetSelectFilter <int_index>

<int_index>

The index of the display filter that you want to check.

Sets your current select filter in the toolbar.

<int >GetNumberSelectFilters

Returns the number select filters in the drop down.

<BOOL>GetDisplayFilter <int_index>

<int_index>

The index of the display filter that you want to check.

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

<void>SetDisplayFilter <int_index> <bool_on>

<int_index>

The index of the display filter that you want to check.

<bool_on>

The state that you want to set the display filter to.

Sets the state of a display filter.

<int>GetNumberDisplayFilters

Returns the number of display filters in the display panel.

<string>GetSelectFilterName <int_index>

<int_index>

The index of the display filter that you want to check.

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

<string>GetDisplayFilterName <int_index>

<int_index>

The index of the display filter that you want to check.

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

See also

class id filter

Main Toolbar

toolMode const StructDef


i-drop - drag and drop

Topic: version 4 MAXScript New Features/i-drop - drag and drop

i-drop drag-and-drop support in MAX allows i-drop-encapsulated files, scripts and texturemaps to be dragged from web pages directly onto a MAX viewport, toolbar or menubar.

Example:

Here is a simple HTML file containing a single i-drop active-X control that represents a MAX file that can be dropped into a MAX viewport. The HTML refers to an XML file containing details about the MAX file to drop. The image proxy, XML file and .max file names specify files on a local G: drive, you will have to adjust these for your setup.

HTML:

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

<meta name="Author" content="Your Name">

<meta name="GENERATOR" content="Mozilla/4.7 [en] (WinNT; U) [Netscape]">

<title>example</title>

</head>

<body>

Here is an i-drop activeX control ....

<p>

<object name="idrop" width="64" height="80" classid="clsid:AF2880B4-B183-11D2-

ADE7-00A0245D8F3F">

<param name="package" value="file:///G:/iDrop/example.xml">

</object>

</body>

</html>

The XML package file:

<?xml version="1.0"?>

<package xmlns="x-schema:http://vizdevel/idrop/idrop-schema.xml">

<proxy defaultsrc="file:///G:/iDrop/blob.gif">

<caption>i-Drop it!</caption>

<img src="file:///G:/iDrop/blob.gif"/>

</proxy>

<dataset>

<datasrc clipformat="CF_IDROP.MAX">

<datafile src="file:///G:/iDrop/foo.max"/>

</datasrc>

</dataset>

</package>

Drag-and-Drop Manager

Interface: dragAndDrop

A new type of datasrc file in an i-drop XML file can be specified that contains a macroScript with drag-and-drop handlers that will be run when you drag and drop the i-drop control onto a MAX viewport. These new kinds of files are called 'drop scripts' and have the suffix .ds . Such files should contain a single macroScript definition with handlers for one or more of the special dropscript events. If there is more than just a single macroScript in the .ds file, all other text is ignored.

Here is a sample XML specifying a dropScript file called "foo.ds":

<?xml version="1.0"?>

<package xmlns="x-schema:http://vizdevel/idrop/idrop-schema.xml">

<proxy defaultsrc="file:///G:/iDrop/blob.gif">

<caption>i-Drop Script!</caption>

<img src="file:///G:/iDrop/blob.gif"/>

</proxy>

<dataset>

<datasrc clipformat="CF_IDROP.MAX">

<datafile src="file:///G:/iDrop/foo.ds"/>

</datasrc>

</dataset>

</package>

dropScript Events

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

on droppable <window> node: point: do ...

on drop <window> node: point: do ...

<window>

a window identifier

node:

any item (scene node) currently under the mouse pointer

point:

If supplied, the 'droppable' handler is called continuously while the i-drop control is dragged over the MAX viewport, and should return true or false depending on whether the item is droppable at that position. If the mouse is not over a scene node, the <item> argument value is undefined. You implement the 'droppable' filter if the dropScript wants to limit droppability in any way.

The 'drop' handler is called when the user finally drops the i-drop control over a viewport and is given the same parameters as 'droppable'.

For example, currently for viewport windows, the full signatures are:

on droppable window node: point: do ...

on drop window node: point: do ...

but since keyword arguments are optional, you can choose any subset of the keyword arguments you need, such as:

on drop window node: do ...

or

on drop window do ...

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.

Example:

Here is a sample 'foo.ds' file.

macroScript foo

(

on droppable window node: return

window == #viewport and

node != undefined and

classOf node == sphere

on drop window node do

(

node.scale *= 1.2

node.material = meditmaterials[1]

)

)

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.

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

)

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

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.

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

Zip-file Script Packages


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 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 Other Interfaces

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

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

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

The above script 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

2 Ways of Accessing the Interface

There are 2 ways to access the interface - as a standalone interface and as an interface on a particular object. If you access the interface directly, you need to pass to it the object to work on.

Example:

m = Bitmaptexture fileName:"L:\mypath\scenes\2500hicon.JPG"
bitmapTex.viewImage m -- direct interface access, need to pass object
m.viewImage() -- accessing interface on object, object internally passed as arg 1.

Associated Method:

getCoreInterfaces()

Returns an array of core interface values.

Example:

The following will list all of the core interfaces.

core_interfaces = getcoreinterfaces()

for i in core_interfaces do (showinterface i;format"\n")

See also

Core Interfaces

Other Interfaces

By Reference Parameter Passing

Dereferencing Operator

Visible Class For '&' Reference Values

Action Manager

Class and Object Inspector Functions Enhanced

Class and Object Inspector Functions


Core Interfaces

Topic: version 4 MAXScript New Features/Interfaces

Interfaces

actionMan

BoneSys

browserMgr

cmdPanel

colorMan

dragAndDrop

HDIKSys

IKSys

manip

maxOps

medit

menuMan

msZip

netrender

NullInterface

objXRefs

paramWire

pluginManager

quadMenuSettings

rollup

SceneExposureControl

SceneRadiosity

timeSlider

trackviews

See also

Other Interfaces

Class and Object Inspector Functions

Class and Object Inspector Functions Enhanced


Other Interfaces

Topic: version 4 MAXScript New Features/Interfaces

Interfaces

bitmapTex

Block_Control

BMP

CameraMap interfaces:

Flex interfaces:

float_list

Float_Reactor

Float_Wire interfaces:

FloatList

FloatReactor

HSDS_Modifier

HSDSObject

IKChainControl

imageMotionBlur

JPEG

Link

Link_Constraint

LookAt_Constraint

Motion_Blur

Orientation_Constraint

path

Path_Constraint

Plugin_Manager

Portable_Network_Graphics

point3_list

Point3_Reactor

Point3_Wire

Point3List

Point3Reactor

Point3Spring

Point_Cache

Point_CacheSpacewarpModifier

PointCache

PointCacheWSM

Position_Constraint

position_list

Position_Reactor

Position_Wire

PositionList

PositionReactor

PositionSpring

radiusManip

RenderElementMgr

rotation_list

Rotation_Reactor

Rotation_Wire

RotationList

RotationReactor

scale_list

Scale_Reactor

Scale_Wire

ScaleList

ScaleReactor

sliderManipulator

SpringPoint3Controller

SpringPositionController

Targa

Unwrap_UVW

uvwMappingHeightManip

uvwMappingLengthManip

uvwMappingUTileManip

uvwMappingVTileManip

uvwMappingWidthManip

UVWUnwrap

Float_Wire

Point3_Wire

Rotation_Wire

Scale_Wire

See also

Core Interfaces

Class and Object Inspector Functions

Class and Object Inspector Functions Enhanced


HD IK controller chains can be assigned to existing hierarchies

Topic: version 4 MAXScript New Features/ IK

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

HD IK controller chains can be assigned to existing hierarchies.

Prototype:

HDIKSys.ikChain <startJoint> <endJoint> <assignEE>

Parameters

<startJoint>

The first node in the new chain, called the ancestor.

<endJoint>

The last node in the chain, called the decendent.

<assignEE>

A boolean parameter: when TRUE, a position end effector is created at the endJoint.

Example:

If 4 boxes existed in the scene and Box02 was a child of Box01, Box03 was a child of Box02, and Box04 was a child of Box03:

HDIKSys.ikChain $Box01 $Box04 TRUE

would assign HD IK controllers and create an end effector at Box04.

Pos/Rotation/Scale Property Access

Pos/Rotation/Scale properties of the nodes are accessible immediately. Instead of writing $node.transform.controller.ik_goal.controller.pos, you can say, in MAXScript, $node.pos.controller, etc.

Note: Both IKControl and IKChainControl can not be instanced.

See also

IKChainControl Interfaces

Interface: HDIKSys

Interface: IKSys

IKLimb Solver


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.

See also

Interface: IKSys

Interface: HDIKSys

HD IK Controller Chains Can Be Assigned to Existing Hierarchies

IKChainControl Interfaces


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. See MultiMaterial : Material


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.

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()". 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.

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 the "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.

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.

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

Return 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.

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

)

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

)

)

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

Menu and CUI Loading

maxOps

Interface: quadMenuSettings

Interface: menuMan

Interface: maxOps


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

particleMesher - superclass: GeometryClass


Network Render Interface

Topic: version 4 MAXScript New Features/Network Render Interface

The interface is fully described here: Interface: NetRender

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 User Reference.

See also

3ds max System Globals


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.

id = $Box01.handle

Returns the unique id associated with the node

A method in the maxOps interface will return a node associated with a given handle.

node = maxOps.getNodeByHandle <number>

Returns the node associated with the id passed in.

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

See also

maxOps


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

Node Common Properties, Operators, and Methods

Node Handles

Class and Object Inspector Functions Enhanced

Access to the Node Bone Properties and Methods


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 Explorer to register with the Windows Registery.

;-------- cut here -------------

REGEDIT

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;

; 1. Change the path in the last line of this file to point at your

; current 3ds max executable directory, then

; 2. Double click this file in Windows Explorer

;

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;

; 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}

HKEY_CLASSES_ROOT\MAX.Application\CurVer = MAX.Application.4

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;; registration info MAX 4.0

; (Application Object)

HKEY_CLASSES_ROOT\MAX.Application.4 = OLE Automation MAX 4.0 Application

HKEY_CLASSES_ROOT\MAX.Application.4\Clsid = {7FA22CB1-D26F-11d0-B260-00A0240CEEA3}

HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-B260-00A0240CEEA3} = OLE Automation MAX 4.0 Application

HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-B260-00A0240CEEA3}\ProgID = MAX.Application.4

HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-B260-00A0240CEEA3}\VersionIndependentProgID = MAX.Application

HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-B260-00A0240CEEA3}\LocalServer32 = C:\3dsmax4\3dsmax.exe

;---- cut here

See also

Setting Up MAXScript OLE Automation

OLE Automation

Running the OLE Demo

Exposing MAXScript Functions

3ds max-Specific Errors


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() method useful here to get a scripter expression for the parent or parent owner.

See also

Interface: paramWire

Float_Wire Interfaces

Position_Wire Interfaces

Rotation_Wire Interfaces

Scale_Wire Interfaces


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.

Methods

plug-inManager.visible = true --show

plug-inManager.visible = false –hide

Show and hide the plug-in manager.

plug-inManager.loadClass <class>

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

Plug-in_Manager Interfaces


maxOps

There are many new MAXScript functions exposed in maxops:

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 <boolean> <integer>

true 1: Enables auto Win/Cross: moving left-to-right is crossing selection

true 0: Enables auto Win/Cross: moving right-to-left is crossing selection

false 1: Disables auto Win/Cross, turns ON crossing selection

false 0: Disables auto Win/Cross, turns OFF crossing selection

The integer relates to the radiobutton index in Customize/Preferences.

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

maxOps.isNetworkLicense

The property is read-only, with a boolean value: true means a network license, false means a local license.

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

Example:

This example displays the values of your Cdilla license.

rollout CdillaOPS "License Properties" width:220 height:270

(

groupBox grp1 "License Values" pos:[18,18] width:180 height:265

button btn5 "Days until Expiration" pos:[50,45] width:119 height:18

editText edt5 "" pos:[50,75] width:119 height:18

button btn6 "License Version" pos:[50,105] width:119 height:18

editText edt6 "" pos:[50,135] width:119 height:18

button btn7 "License Behavior" pos:[50,165] width:119 height:18

editText edt7 "" pos:[50,195] width:119 height:18

button btn8 "Hardware Lock ID" pos:[50,225] width:119 height:18

editText edt8 "" pos:[50,255] width:119 height:18

on btn5 pressed do

edt5.text = (maxOps.licenseDaysLeft as string)

on btn6 pressed do

(

version = maxOps.productVersion as string

edt6.text = substring version 15 version.count

)

on btn7 pressed do

(

version = maxOps.licenseBehavior as string

edt7.text = substring version 16 version.count

)

on btn8 pressed do

edt8.text = (hardwarelockid as string)

)

rof = newRolloutFloater "License_Status" 230 380

addRollout CdillaOPS rof

maxOps.getNodeByHandle

Returns the node associated with the id passed in.

maxOps.setSelectionType <auto> <method>

<auto>

True or False

<method>

Valid values or method are #window, #crossing, #leftToRight, #rightToLeft. #window or #crossing is to be used if the first argument (auto) is false. #leftToRight or #rightToLeft is to be used when auto is true.

maxOps.trackBar

maxOps.getTrackBar()

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

Note: The following properties require a redraw, but in some cases hiding and unhiding the trackbar gives a better result.

maxOps.trackBar.showFrames

maxOps.trackBar.showAudio

maxOps.trackBar.showSelectionRange

maxOps.trackBar.showSnapToFrames

Example:

tbar = maxops.trackbar

tbar.showframes = false

tbar.redraw() -- Notice the result so far

tbar.visible = false

tbar.visible = true -- Notice the difference

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

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.

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.

This method will return true if successful, otherwise it will return false.

maxOps.CollapseNode node noWarnings

maxOps.CollapseNodeTo node modIndex noWarnings

See also

Interface: maxOps

ItrackBar

Node Handles

3ds max System Globals


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

ApplyOperation Function

Menu Manager

Interface: menuMan

Menu and CUI Loading


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

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

Float_Reactor Interfaces

Point3_Reactor Interfaces

Scale_Reactor Interfaces

Position_Reactor Interfaces


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

This is the interface for the Render Element Manager.

See also

Interface: maxOps

Combustion


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

Scripted Plug-in Events

Scripted Cameras


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.

See also

Scripted Plug-ins

type:#integer Parameters in Scripted Plug-in Parameter Blocks

Scripted Cameras


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.

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

Scripted Plug-in Events

type:#integer Parameters in Scripted Plug-in Parameter Blocks

Scripted Cameras


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


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 values. A matrix3 value is a 4x3 3D transformation matrix.

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

See also

transform_script - superclass: Matrix3Controller

Script Controllers


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 standalone objects, like the slider manipulator. These are usually used in conjunction with parameter wiring to get make them useful.

To create a standalone manipulator, you go to the "Helpers" section of the create panel, and select "Manipulators" in the drop-down list.

Standalone 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.

Scripted Manipulators

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, so if you want to write your own manipulator, it would be a good idea to read about Scripted Plug-ins first. They are very similar to scripted geometry objects.

3 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 standalone manipulator

  • UVWManip.ms -- A set of manipulators for the UVW modifier

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

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

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.

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.

Standalone Manipulators

Standalone 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 standalone manipulators can be saved in the MAX file, it needs a class ID. 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.

Standalone manipulators manipulate themselves, so the "canManipulate" handler looks like this:

on canManipulate target return (classOf target) == sliderManipulator

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 standalone manipulator also needs some special code in its "updateGizmos" handler. For the slider this looks like:

-- If this is not a standalone 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 standalone object. When the object is standalone, 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.

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

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.

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.

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 UVWManip.ms for an example of creating 3D gizmos with GizmoShape.

See also

Interface: manip

sliderManipulator Interfaces

radiusManip Interfaces

uvwMappingHeightManip Interfaces

uvwMappingLengthManip Interfaces

uvwMappingUTileManip Interfaces

uvwMappingVTileManip Interfaces

uvwMappingWidthManip Interfaces

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper


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


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

Rollout Floater Windows


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

<float>getMass()

Returns the mass.

<void>setMass <float>mass

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.

<float>getDrag()

Returns the drag.

<void>setDrag <float>drag

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.

<float>getTension <index>springIndex

Gets the tension for the spring corresponding to the index.

<void>setTension <index>springIndex <float>tension

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

<float>getDampening <index>springIndex

Gets the dampening for the spring corresponding to the index.

<void>setDampening <index>springIndex <float>dampening

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.

<boolean>addSpring <node>node

<node>node

Adds the node to the spring list.

Returns true if successful, false otherwise

<integer>getSpringCount()

Returns the number of springs in the spring system.

<void>removeSpringByIndex <index>springIndex

Removes the spring corresponding to the index.

<void>removeSpring <node>node

Removes the spring if the node is in the spring list.

See also

PositionSpring Interfaces

Point3Spring Interfaces

SpringPoint3Controller Interfaces

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController Interfaces

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex Interfaces

flexOps const StructDef


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

System Information

sysInfo const StructDef


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.

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

Methods:

<void>redraw forceRedraw:<bool>

forceRedraw default value: false

Indicates if the redraw should be forced

Redraws the trackbar.

<time>getNextKeyTime()

Gets the next key time. The "at time" context can be used to determine the starting point.

<time>getPreviousKeyTime()

Gets the previous key time. The "at time" context can be used to determine the starting point.

See also

maxOps

Interface: maxOps


Trackviews

Topic: version 4 MAXScript New Features/ Trackviews

trackviews.isOpen <fpvalue>name or index

Returns a boolean value indicating if the specified trackview is open.

trackviews.isCurrent <fpvalue>name or index

Returns a boolean value indicating if the trackview is the last one used or not.

trackviews.setCurrent <fpvalue>name or index

Sets the specified trackview to be the current one. Returns true if successful.

trackviews.currentTrackView

Read only property that returns the interface for the currently used trackview. Returns undefined if the trackview is closed.

trackviews.lastUsedTrackViewName

Read only property that returns the name of the current trackview.

trackviews.openLastUsedTrackView()

Opens the current trackview if it has been closed.

trackviews.delete <fpvalue>name or index

Deletes the specified trackview.

trackviews.close <fpvalue>name or index

You can now close a trackview based on it's index or name.

trackviews.open <fpvalue>name or index

You can now open a trackview based on it's index or name.

trackviews.getTrackView <fpvalue>name or index

This method will get a trackview based on it's index or name.

Example:

showInterface (trackviews.getTrackView 1)

trackviews.getAllTrackViews()

The above script returns an array of trackviews.

trackviews.numTrackViews()

Returns the number of trackviews.

trackviews.getTrackViewName <index>index

Returns the name of the trackview window based on the index.

<void>setName <string>name

Sets the name of the trackview window

<integer>getNumTracks()

Gets the number of tracks currently displayed in trackview

<integer>numSelTracks()

Gets the number of selected tracks

<boolean>canAssignController()

Tests to see if all selected tracks are of the same type

<void>assignControllerDialog

Invokes the assign controller dialog if canAssignController()

<boolean>assignController <maxObject>controller

Assigns the controller to the selected tracks if canAssignController() is true and the controller is the appropriate type

<void>showControllerTypes <boolean>state

Sets the ShowControllerType property

<void>expandTracks()

Expands all tracks

<void>zoomSelected()

Zooms to the selected object's track

<void>zoomOnTrack <maxObject>parent <index>subNum

Zooms to the track defined by the parent and the subNum

<maxObject>getTrack <index>index

Returns the object belonging to the indexed track

<maxObject>getParent <index>index

Gets the parent of the object belonging to the index track. If the object is a position controller, the parent is the Transform controller

<maxObject>getSelected <index>index

Gets the objects belonging to the selected, indexed track

<maxObject>getParentOfSelected <index>index

Gets the indexed selected tracks parent object

<index>getSelectedSubNum <index>index

Gets the subNum of the selected track

<index>getIndex <maxObject>object

Gets the index for the animatable object

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

Selects tracks by index

<boolean>selectTrack <maxObject>object <boolean>clearSelection

Selects tracks by object

A trackview interface can be obtained for one of the currently open trackviews using one of the following methods.

trackviews.getTrackViewByName <name as string>

trackviews.getTrackViewByIndex <index as int>

trackviews.getAllTrackViews()

Once you have an instance of the trackview interface you can call the following new methods on it.

getEditMode()

Gets the current edit mode as an symbolic enum.

setEditMode <type as symbolic enum>

Sets the current edit mode

editMode

Property to do the same as the above two methods

Valid symbolic enum values are:

#editKeys

#editTime

#editFCurves

#editRanges

#positionRanges

See also

trackView const StructDef

Interface: trackviews

Track View


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 standalone Utility plug-in named "Visual MAXScript"

    When accessed as a Utility through the Utility command panel, the layout editor operates in a "standalone" 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.

  • Through two 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.

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

  • 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. See ActiveX Controls in MAXScript Rollouts

  • 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. See Interface: objXRefs

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.

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

XRefScene Values

XRefObject : Node

xrefs const StructDef

xrefPaths const StructDef

Interface: objXRefs


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.

  • As executable files inside other .mzp archives, you can nest them if want.

  • When using the fileIn <fileName> function, 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.

Example:

name "test package"

version 3

treeCopy flobber to $scripts

copy *.ms to $scripts\flobber\dobber

move foo.max $scenes

drop $scenes\foo.max

The zip package is a text file that contains one or more of the following commands. All are optional.

name "<package_name>"

Names the package.

description "<text>"

Describes the package. Normally, a readme file in the package would give extended operating instructions, if they are provided.

version <number>

Returns the version number of the package.

extract to "<directory>"

Specifies the location in which to extract the contained files. This can be an absolute path name (starting with a drive letter or \) or a relative name. Relative names are taken as being relative to the default temp directory. The special prefix $max can be used to specify the main MAX executable directory

run "<script_file_name>"

If the package is launched from a MAXScript run menu item or via a fileIn() function, run the named script file. There can be more than one run command and they are run in order. These are ignored if the package is launched via a fileIn() call that is supplied with an explicit script file to run.

drop "<dropScript_file_name>"

If the package is launched by drag-and-drop into MAX, run the named dropScript file. There can only be one of these per msp.startup file.

copy "<files>" to "<directory>"

Copies the named file or files (if the <files> string contains wild-cards) to the given directory. The special $max prefix can be used here.

clear temp

Cause the temporarily-extracted files to be deleted once all the nominated scripts are run or dropped.

clear temp on MAX exit

Cause the temporarily-extracted files to be deleted when the currently running MAX session exits.

clear temp on reset

Cause the temporarily-extracted files to be deleted when a file open or reset is performed.

keep temp

Prevents any deletion of the extracted files.

File Searches:

The following functions will perform searches for files given as relative file names in the current package file:

fileIn <filename>

include <filename>

openBitmap <filename>

editScript <filename>

Note

Any saves will not go back into the package, but into the temp extracted file.

loadMAXFile <filename>

mergeMAXFile <filename> ...

getMAXFileObjectNames <filename>

importFile <filename> ...

loadMaterialLibrary <filename>

Bitmap Searches:

The following UI items will search for named bitmap .bmp files in the package:

bitmap <name> fileName:<filename>

button <name> images:<image_spec_array>

checkButton <name> images:<image_spec_array>

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

fileIn "libs/myFns.ms"

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

Copy and Move:

copy "<from>" to "<to>" [noReplace]

move "<from>" to "<to>" [noReplace]

treeCopy "<from>" to "<to>" [noReplace]

treeMove "<from>" to "<to>" [noReplace]

These cause files from within the package to be copied or moved as specified. The treeCopy & treeMove variants move whole nested directories of files. By default, any existing files in the destination location are replaced with the newly extracted ones, add the 'noReplace' keyword to prevent this.

The <to> spec must always be a directory. Any treeCopy/Move replicates the source sub-directories into the <to> directory, making new directories as needed. The <from> spec for copy & move may be any relative or fully specified file name or wild-card pattern. Relatively named files are looked for in that relative position in the package. Fully specified names are looked for in the main file-system.

The <from> spec for treeCopy/Move may be just a directory path, in which case the whole directory and its subdirectories are copied/moved, or it can be a wild-card path name in which case just the matching files or directory trees are copied/moved.

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

$plugins - 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 "$plugins"

move "*.max" to "$scenes"

move "texmaps\*.bmp" to "$maps"

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

Open, Merge, Xref and Import:

open <max_file_name> -- opens the named MAX scene file

merge <max_file_name> -- merges the named MAX scene file

xref <max_file_name> -- xref the named MAX scene file

import <importable_file_name> -- imports the named file

Only one 'open' or 'import' command may be used per mzp.run file. Any number of merge and xref commands can be used.

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 has exposed 2 scripter-callable functions:

msZip.fileInPackage <mzpFilename> &<exractDirVar>

The 'fileInPackage' function is essentially the equivalent of:

fileIn <mzpFileName>

and will return true if success or false if there is a failure, or a missing or invalid .mzp file, and it will also return the directory that the package file were extracted to in the pass-by-reference <extractDirVar> argument.

Example:

local extractDir = ""

if msZip.fileInPackage "foo.mzp" &extractDir then

(

-- extractDir contains the extracted-to directory name

...

)

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

The 'unloadPackage' function performs an extract and executes all the file copying and moving commands in any enclosed mzp.run file, but will not execute any scripts in the package. The extractTo directory and any 'drop' command file found will be returned in the pass-by-reference arguments.

Example:

local extractDir = "", dropFile = ""

if msZip.unloadPackage' "foo.mzp" &extractDir &dropFile then

(

-- extractDir contains the extracted-to directory name

-- dropFile contains any found drop file name (the path to extracted location )

...

)

See also

i-drop - drag and drop


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

RubberBanding in pickObject() Function


Affect Region Function

Topic: version 4 MAXScript Language Improvements/Language Improvements

float> affectRegionVal <distance_float> <falloff_float> <pinch_float> <bubble_float>

The standard affect region function, based on a distance and the three affect region parameters (same as the editable mesh). This function is a cubic curve which returns 1 at distance 0, 0 if distance is greater than falloff, and other values for distance between 0 and falloff.

This is the function used inside the Affect_Region modifier. For the different editables, one of the data channels is the selection weight. If you wanted to, you could use this function to calculate the vertex selection weights on you own.

See also

Affect_Region : Modifier


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

Class and Object Inspector Functions Enhanced


BinStream for Binary Reading and Writing

Topic: version 4 MAXScript Language Improvements/Language Improvements

BinStream fopen <String fileName> <String mode>

Opens a file for reading or writing based on the mode parameter. This can either be "wb" for Writing Binary or "rb" for Reading Binary. The function will return a BinStream value.

Boolean FClose <BinStream>

Close a BinStream value. Returns True if it successfully closed the BinStream.

Boolean fseek <BinStream> <Integer> <#seek_set | #seek_cur | #seek_end>

Move the file pointer to the specified location based off the seek parameter.

#seek_set - base off start of file.

#seek_cur - base off current position.

#seek_end - base off end of file.

Integer ftell <BinStream>

Returns the current file pointer position.

Boolean WriteByte <BinStream> <Integer> [#signed | #unsigned]

Writes a Integer to the file as one byte. Returns True if write was successful.

Boolean WriteShort <BinStream> <Integer> [#signed | #unsigned]

Writes a Integer to the file as two bytes. Returns True if write was successful.

Boolean WriteLong <BinStream> <Integer> [#signed | #unsigned]

Writes a Integer to the file as four bytes. Returns True if write was successful.

Boolean WriteFloat <BinStream> <Float>

Writes a Float to the file as four bytes. Returns True if write was successful.

Boolean WriteString <BinStream> <String>

Writes a string to the file. Returns True if write was successful.

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

Read a one byte value and return as an Integer.

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

Read a two byte value and return as an Integer.

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

Read a four byte value and return as an Integer.

Float ReadFloat <BinStream>

Read a four byte value and return as an Float.

String ReadString <BinStream>

Read a string from the file.

Example:

f=fopen "c:\\test.bin" "wb"

WriteString f "String"

WriteByte f 64

WriteShort f 128

WriteLong f 256

WriteFloat f 512.0

WriteString f "gnirtS"

WriteLong f (ftell f)

fclose f

f=fopen "c:\\test.bin" "rb"

ReadString f

ReadByte f

ReadShort f

ReadLong f

ReadFloat f

ReadString f

ftell f

ReadLong f

fclose f

See also

FileStream Values


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.

System Exception Note:

The following example is an error:

fn test1 &p3 = return &p3.x

p=[1,2,3]

r=test1 p

*r

Result: access violation!

It is an error to pass back a reference to a local that has gone from the call stack, but it is very difficult to detect this efficiently. Be careful not to pass back &refs to local variables as it may cause system exceptions.

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

The above example 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

in the body of foo will cause x * y to be assigned to the var2 local in the caller. After

var1 = foo 2 3 &var2

var1 will contain true and var2 will contain x * y or 6.

Any number of by-reference parameters can be used and they can be keyword parameters if needed:

fn foo x y &z: = ...

called like this:

var1 = foo 2 3 z:&var2

The '&' reference operator used to supply references in a call can be applied to any <accessor> construct in MAXScript. These are:

variables (locals, globals, rollout locals, plug-in locals, etc.)

property access

array index

parameter (of a scripted plug-in)

Example:

p = [1, 2, 3]

foo 2 3 &p.x

would cause the x coordinate in the point to be passed by-reference and so after the call, the value in p would be

[6, 2, 3]

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

Visible Class For '&' Reference Values


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

Source Code Layout

Source Code Layout and Continuation Lines


Coercion of bitArray to Array and Integer Arrays to bitArrays

Topic: version 4 MAXScript Language Improvements/Language Improvements

Coercion of bitArray to array and integer arrays to bitArrays implemented.

<bitArray> as array

<integer array> as bitArray

Example:

a=#{1..5,10}

b=a as array

c=b as bitarray

If an element of the array cannot be coerced to an integer, and error is thrown .numberSet and .isEmpty are read-only properties, which have been added to the BitArrayValue class.

.numberSet

Returns the number of bits set

.isEmpty

Returns true if no bits are set and false if one or more bits are set.

Example:

a=#{1..5,10..20}
a.numberset --> 16
a.isEmpty --> false
a=#{}
a.numberset --> 0
a.isEmpty --> true

The '*' operator has been added to bitArrays which performs an 'AND' operation:

<bitarray> * <bitarray> -- intersection ("AND" operation)

See also

BitArray Values

Value Common Properties, Operators, and Methods


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


Detecting Deleted Nodes

Topic: version 4 MAXScript Language Improvements/Language Improvements

<node> == undefined and <node> != undefined

When a node has been deleted, the two statements above return false and true, respectively.

Example:

if mynode != undefined and not isdeleted myNode do ...

See also

isValidNode

Node Common Properties, Operators, and Methods


Dereferencing Operator

Topic: version 4 MAXScript Language Improvements/Language Improvements

Visible Class For '&' Reference Values

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:

*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


forceUpdate Function added to UVWUnwrap

Topic: version 4 MAXScript Language Improvements/Language Improvements

Unwrap_UVW : Modifier

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

Unwrap_UVW Interfaces


hasProperty() function

Topic: version 4 MAXScript Language Improvements/Language Improvements

hasProperty <obj> <prop_name_or_pattern_string>

Returns true if the object has the given property.

See also

Properties, Methods, Operators, and Literals


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


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


isValidNode

Topic: version 4 MAXScript Language Improvements/Language Improvements

isValidNode <var>

Returns true if <var> is a node value, and the node has not been deleted. False otherwise.

See also

Detecting Deleted Nodes

Node Common Properties, Operators, and Methods


RubberBanding in pickObject() Function

Topic: version 4 MAXScript Language Improvements/Language Improvements

The pickObject() function in MAXScript now supports 2 new optional keyword arguments for controlling the display of a rubber-banding line in the viewport during pick operations. The new keywords are:

rubberBand:<point3>

rubberBandColor:<color>

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

Example:

obj2 = pickObject rubberBand:obj1.pos rubberBandColor:yellow

See also

Picking Scene Nodes By Hit

Additional Keyword Parameter On pickObject()


SetDir

Topic: version 4 MAXScript Language Improvements/Language Improvements

SetDir <filetype_name> <string>

Sets the directory specified in string. Replicated in the Customize > Configure Paths dialog for the specified file type.

The valid <filetype_name> values are:

#autoback

#drivers

#export

#expression

#font

#help

#image

#import

#matlib

#maxroot

#maxstart

#plugcfg

#preview

#scene

#scripts

#sound

#startupScripts

#ui

#vpost

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

See also

3ds max System Directories


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

Interface: actionMan


startObjectCreation()

Topic: version 4 MAXScript Language Improvements/Language Improvements

The startObjectCreation() function has been enhanced.

startObjectCreation <maxobjclass> [returnNewNodes:<flag>] [newNodeCallback:<fn>]

The values that can now be supplied to the optional 'returnNewNodes:' keyword argument are true, false (the default) or #first. If 'true' is supplied, all of the nodes created, up until the current create mode is exited, will be returned in an array. If #first is supplied, only the first node created is returned, immediately after it is created. The function doesn't wait for the create mode to be exited by the user.

The optional 'newNodeCallback:' keyword argument can supply a scripted function of one argument to the create mode that is started, such that the function will be called each time a node is created with the new node as its argument. This is similar to supplying pickObject() filter functions, although the return value of the newNodeCallback: function is ignored. Note that the callback function is invoked immediately upon new node creation, *before* any base object is installed in it, so *only* node-related properties can be accessed and changed during this callback.

Example:

fn setColor n = n.wireColor = red

startObjectCreation box newNodeCallback:setColor

would cause all new boxes created in the started create mode to have red wire color.

The 'returnNewNodes:' and 'newNodeCallback:' can both be supplied on the same call; the callback will be called on each node, and they will be returned in an array as the result of the startObjectCreation() function.

See also

Create Panel

Defining Macro Scripts

Change Handlers and Callbacks

callbacks const StructDef


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 3ds max Objects


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

Scripted Plug-ins


Symbolic Pathnames

Topic: version 4 MAXScript Language Improvements/Language Improvements

Support for $<name> symbolic pathnames to all the places that filenames can be supplied for opening things in MAXScript. Any filename you give to MAXScript in the following situations can begin with a '$' followed by one of the symbolic directory names below.

Example:

fileIn "$scripts\foo.ms"

This example will open the file "foo.ms" in the current MAX scripts directory.

The situations in which MAXScript honors '$' symbolic directories are as follows:

Functions

fileIn()

openBitmap()

createBitmap() in the fileName: parameter

render() in the outputFile: parameter

Compiler directives:

include <filename_string>

Rollouts:

Any bitmap image file names for buttons, checkbuttons, bitmap

The following symbolic names are recognized:

$max - main MAX executable directory

$maps - first directory in Maps directory config

$scenes - scenes directory

$fonts - fonts directory

$imports - imports directory

$sounds - sounds directory

$matlibs - matlibs directory

$scripts - scripts

$startupScripts - auto-load startup scripts

$plugins - 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 filetype_names which start with a "#".

See also

Zip-file Script Packages

3ds max System Globals


System Information

sysInfo const StructDef

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.tempdir

A read only variable to get the Temp directory as a <string> value.

sysInfo.currentdir

Variable to get/set the current directory as a <string> value.

sysInfo.username

A read only variable to get the user name as a <string> value.

sysInfo.computername

A read only variable to get the computer name as a <string> value.

sysInfo.cpucount

A read only variable to get the number of CPUs as a <integer> value.

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

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

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

See also

System Tools


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.

See also

Scripted Plug-ins

Scripted Custom Attributes

Menu Manager


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.

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

Modifier Common Properties, Operators, and Methods


Visible Class For '&' Reference Values

Topic: version 4 MAXScript Language Improvements/Language Improvements

Dereferencing Operator

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.

See also

By Reference Parameter Passing

Dereferencing Operator


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

Example:

lst = $.pos.controller -- if this is a list controller

showInterfaces lst -- interface name is "list"

Methods

lst.getCount()

Returns the count function.

lst.count

Returns count property (read only).

lst.SetActive <index>

Set active function

lst.GetActive()

Get active function

lst.active

Get/set active property.

lst.cut <index>

Cut the indexed sub-controller

lst.paste <index>

Paste clip to index location.

lst.delete <index>

Delete the indexed sub-controller.

lst.setName <index> <string>

Sets the name of the indexed sub-controller.

lst.getName <index>

Gets the name of the indexed sub-controller.

Example:

b = Box lengthsegs:1 widthsegs:1 heightsegs:1 length:65.7611 width:32.0211 height:39.8261 pos:[-15.6972,-84.9615,0] isSelected:on

b.pos.controller = position_list ()

b.pos.controller.Available.controller = Position_XYZ ()

b.pos.controller.Available.controller = tcb_position ()

b.pos.controller.Available.controller = bezier_position ()

lst = b.pos.controller -- the list controller

showInterfaces lst -- interface name is "list"

lst.getCount() -- count function

lst.count -- count property (read only)

lst.SetActive 3 -- set active function

lst.GetActive() -- get active function

lst.active -- active property

lst.cut 2 -- cut the second sub-controller

lst.paste 1 -- paste it to the top of the list

lst.delete lst.count -- delete the second to last sub-controller

lst.setName 2 "My Bezier" -- sets the name of the second sub-controller

lst.getName 2 -- gets the name of the sub-controller

See also

List Controllers


mapKeys() method

Topic: version 4 MAXScript Language Improvements/ Controllers

The mapKeys() method gives access to the SDK function Control::MapKeys().

The form is:

mapKeys <max_object> (<map_struct> | <fn> <arg>) [#allKeys] [#selection] * [#slide] [#rightToLeft]

This is like other recursive controller key functions 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 map 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.

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

Nested Object Controller Functions

Controller Time Functions

Controller Key Functions

MAXKeyArray Values


moveKeys function

Topic: version 4 MAXScript Language Improvements/ Controllers

moveKeys <key_array> <time> [ #selection ]

Moves all keys by the time given. If #selection is specified, move the current selection otherwise move all keys.

The 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

Nested Object Controller Functions

Controller Time Functions

Controller Key Functions

MAXKeyArray Values


Hose - superclass: GeometryClass

Hose - superclass: GeometryClass; super-superclass:node - 27:0 - classID: #(1777953373, 593249034)

The Hose object is a flexible object that you can connect between two objects, whereupon it reacts to their movement. It's similar to Spring, but does not have dynamics properties. You can specify the overall diameter and length of the hose, the number of turns, and the diameter and shape of its "wire."

Constructor

Hose ...

Properties

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

<Hose>.Generate_Mapping_Coordinates Integer default: 0 -- integer

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

<Hose>.Hose_Height Float default: 1.0 -- animatable; float

Use this field/spinner to set the straight-line height or length of the hose when it is not bound. This is not the actual length of the hose. Available only when Free Hose is chosen.

<Hose>.Segments_Along_Hose Integer default: 45 -- animatable; integer

The total number of segments in the hose's length. Increase this setting for a smooth profile when the hose is curved. Default=16.

<Hose>.Smooth_Spring Integer default: 0 -- integer

Choose one of the following smoothing options:

All: The entire hose is smoothed.

Sides: Smoothing is applied along the length of the hose but not around its circumference.

None: No smoothing is applied.

Segments: Smoothing is applied only on the inner section of the hose.

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

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

<Hose>.Hose_Cross_Section_Type Integer default: 0 -- integer

Sets a circular cross-section.

Lets you specify different settings for width and depth.

Similar to Rectangular Hose, but rounds one side for a D-shaped cross-section.

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

The maximum width of the hose at the ends.

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

The number of sides of the hose. A Sides setting of 3 gives a triangular cross-section; 4 gives a square cross-section; and 5 gives a pentagonal cross-section. Increase Sides for a circular cross-section. Default=6.

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

The width of the hose.

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

The height of the hose.

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

The amount by which the cross-section corners are rounded. For this to be visible, Fillet Segs must be set to 1 or higher. Default=0.

<Hose>.Rectangular_Hose_Fillet_Segs Integer default: 0 -- animatable; integer

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

<Hose>.Rectangular_Hose_Section_Rotation Float default: 0.0 -- animatable; angle; Controller Scaling: (1 : 57.2958)

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

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

The width of the hose.

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

The height of the hose.

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

The amount by which the two cross-section corners opposite the rounded side are rounded. For this to be visible, Fillet Segs must be set to 1 or higher. Default=0.

<Hose>.D_Section_Hose_Fillet_Segs Integer default: 0 -- animatable; integer

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

<Hose>.D_Section_Hose_Round_Segs Integer default: 8 -- animatable; integer

The number of segments on the rounded side. Increase for a smoother profile. Default=4.

<Hose>.D_Section_Hose_Section_Rotation Float default: 0.0 -- animatable; angle; Controller Scaling: (1 : 57.2958)

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

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

When on, lets you set the following four parameters for the central, flexible section of the hose. When off, the hose's diameter is uniform throughout its length.

<Hose>.Flex_Section_Start Float default: 10.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)

The percentage of the hose length from the starting extremity of the hose at which the flex section begins. By default, the starting end of the hose is the end at which the object pivot appears. Default=10%.

<Hose>.Flex_Section_Stop Float default: 90.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)

The percentage of the hose length from the end extremity of the hose at which the flex section begins. By default, the end extremity of the hose is opposite the end at which the object pivot appears. Default=90%.

<Hose>.Flex_Cycle_Count Integer default: 5 -- animatable; integer

The number of corrugations in the flex section. The number of visible cycles is limited by the number of segments; if Segments isn't high enough to support the number of cycles, then not all cycles will appear. Default=10.

Tip: To set the appropriate number of segments, first set Cycles, and then increase Segments until the number of visible cycles stops changing.

<Hose>.Flex_Section_Diameter Float default: -20.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)

The relative width of the "outside" parts of the cycles. At negative settings, these are smaller than the overall hose diameter. At positive settings, these are larger than the overall hose diameter. Default=-20%. Range=-50% to 500%.

<Hose>.Top_Tension Float default: 100.0 -- animatable; float

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

<Hose>.Bottom_Tension Float default: 100.0 -- animatable; float

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

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Drag - superclass: SpacewarpObject

Drag - superclass: SpacewarpObject; super-superclass:node - 29:0 - classID: #(1173650369, 674975258)

The Drag space warp is a particle motion damper that reduces particle velocity by a specified amount within a specified range. The damping can be applied linearly, spherically, or cylindrically. Drag is useful for simulating wind resistance, transfers into dense media (like water), impacts with force fields, and other, similar situations.

With each damping type, you can control the damping effect along several vectors. The damping is also affected by particle system settings, such as speed.

Constructor

Drag ...

Properties:

<Drag>.'time on' Integer default: 0 -- integer; Time_On

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

<Drag>.'time off' Integer default: 16000 -- animatable; integer; Time_Off

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

<Drag>.symmetry Integer default: 0 -- radio button number; Damping_Symmetry

This group lets you choose Linear Damping, Spherical Damping, or Cylindrical Damping, plus a set of parameters for each.

<Drag>.dampingx Float default: 5.0 -- animatable; percentage; X_Damping; Controller Scaling: (1 : 100.0)

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

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

Sets the thickness of the "range plane," or the infinite plane perpendicular to the specified axis. Takes effect only when Unlimited Range is turned off.

<Drag>.falloffx Float default: 1000.0 -- animatable; float; X_Falloff

Specifies the distance beyond the X, Y, or Z Range within which Linear Damping is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off.

<Drag>.dampingy Float default: 0.0 -- animatable; percentage; Y_Damping; Controller Scaling: (1 : 100.0)

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

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

Sets the thickness of the "range plane," or the infinite plane perpendicular to the specified axis. Takes effect only when Unlimited Range is turned off.

<Drag>.falloffy Float default: 1000.0 -- animatable; float; Y_Falloff

Specifies the distance beyond the X, Y, or Z Range within which Linear Damping is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off.

<Drag>.dampingz Float default: 0.0 -- animatable; percentage; Z_Damping; Controller Scaling: (1 : 100.0)

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

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

Sets the thickness of the "range plane," or the infinite plane perpendicular to the specified axis. Takes effect only when Unlimited Range is turned off.

<Drag>.falloffz Float default: 1000.0 -- animatable; float; Z_Falloff

Specifies the distance beyond the X, Y, or Z Range within which Linear Damping is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off.

<Drag>.dampingr Float default: 5.0 -- animatable; percentage; Radial_Damping; Controller Scaling: (1 : 100.0)

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

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

Specifies the distance from the center of the Drag icon, in system units, within which damping is in full effect. Takes effect only when Unlimited Range is turned off.

<Drag>.falloffr Float default: 1000.0 -- animatable; float; Radial_Falloff

Specifies the distance beyond the Radial/Tangential Range within which Linear Damping is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off.

<Drag>.dampinggc Float default: 0.0 -- animatable; percentage; Tangential_Damping; Controller Scaling: (1 : 100.0)

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

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

Specifies the distance from the center of the Drag icon, in system units, within which damping is in full effect. Takes effect only when Unlimited Range is turned off.

<Drag>.falloffgc Float default: 1000.0 -- animatable; float; Tangential_Falloff

Specifies the distance beyond the Radial/Tangential Range within which Linear Damping is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off.

<Drag>.dampingrc Float default: 5.0 -- animatable; percentage; Radial_Damping; Controller Scaling: (1 : 100.0)

Damping controls the percentage of particle motion toward or away from the center of the circular portion of the icon (Radial), across the radial vector (Tangential), or along the length of the icon's long axis (Axial) that's affected by the damping, on a per-frame basis.

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

Specifies the distance from the center of the Drag icon, in system units, within which Radial and Axial damping are in full effect. Range also specifies the thickness of the infinite plane that governs the range of Axial damping. Takes effect only when Unlimited Range is turned off.

<Drag>.falloffrc Float default: 1000.0 -- animatable; float; Radial_Falloff

Specifies the distance beyond the Radial/Tangential/Axial Range within which Linear Damping is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off.

<Drag>.dampingc Float default: 0.0 -- animatable; percentage; Tangential_Damping; Controller Scaling: (1 : 100.0)

Damping controls the percentage of particle motion toward or away from the center of the circular portion of the icon (Radial), across the radial vector (Tangential), or along the length of the icon's long axis (Axial) that's affected by the damping, on a per-frame basis.

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

Specifies the distance from the center of the Drag icon, in system units, within which Radial and Axial damping are in full effect. Range also specifies the thickness of the infinite plane that governs the range of Axial damping. Takes effect only when Unlimited Range is turned off.

<Drag>.falloffc Float default: 1000.0 -- animatable; float; Tangential_Falloff

Specifies the distance beyond the Radial/Tangential/Axial Range within which Linear Damping is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off.

<Drag>.dampingax Float default: 0.0 -- animatable; percentage; Axial_Damping; Controller Scaling: (1 : 100.0)

Damping controls the percentage of particle motion toward or away from the center of the circular portion of the icon (Radial), across the radial vector (Tangential), or along the length of the icon's long axis (Axial) that's affected by the damping, on a per-frame basis.

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

Specifies the distance from the center of the Drag icon, in system units, within which Radial and Axial damping are in full effect. Range also specifies the thickness of the infinite plane that governs the range of Axial damping. Takes effect only when Unlimited Range is turned off.

<Drag>.falloffax Float default: 1000.0 -- animatable; float; Axial_Falloff

Specifies the distance beyond the Radial/Tangential/Axial Range within which Linear Damping is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off.

<Drag>.rangeless BooleanClass default: true -- boolean; Unlimited_Range

<Drag>.iconsize Float default: 10.0 -- float; Icon_Size

Specifies the size of the icon.

Example:

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

See also

Modifier and SpacewarpModifier Types


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 3ds 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>.Vertex_Count Integer default: 0 -- animatable; integer

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

<MultiRes>.Vertex_Percentage Float default: 100.0 -- animatable; float

The modified object's vertex count as a percentage of the overall number of vertices in the original mesh. Adjusting this setting alters the Count value as well.

Note: After you type in a specific percentage, such as 30, you might find that the software changes the value to a slightly lower one, such as 29.971. This is due to the relationship between the overall number of vertices in the model and the percentage calculation. It is not a bug, but simply the closest solution to your request.

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

When on, lets MultiRes merge vertices between discrete elements in a model.

For example, if you apply MultiRes to a teapot, which comprises four separate elements, and turn on Vertex Merging, as you adjust the vertex resolution, the separate components will meld together into one contiguous lower-resolution object.

To control Vertex Merging, you can set a Merge Threshold. This value determines the 3ds max unit distance within which to merge elements.

<MultiRes>.Threshold Float default: 0.0 -- float

This spinner value sets the maximum distance in 3ds max units between vertices in order for those vertices to be considered for merging. Once this threshold is achieved, then the vertices between elements will be welded together as the mesh is reduced in complexity.

Note: To eliminate only coincident vertices, set Merge Threshold to 0.0. This is similar to the Weld Vertex function.

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

When on, MultiRes merges the boundaries of adjacent elements and vertices within elements. Many objects can contain multiple groups of vertices that don't share connectivity. A simple example of this is the Teapot object. It comprises four different elements: the body, the handle, the spout, and the lid. Normally, MultiRes optimizes each discrete element in a mesh on its own.

The default behavior of the Vertex Merging option is to merge vertices between elements. Turning on Within Mesh? causes vertices within elements to be merged as well.

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

When on, MultiRes preserves materials assigned to the selected model. The material boundaries defined by Material IDs are retained as long as possible, and are the last to be eliminated at low vertex counts. Default=off.

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

When on, overrides the MultiRes optimization algorithms and preserves any vertices selected at the MultiRes Vertex sub-object level as "critical" ones. Use this feature to retain critical features of an object or character such as its fingers or claws, or other geometry that might become unrecognizable if reduced too severely.

To select vertices for use with this option, use the MultiRes Vertex sub-object level. To access this level, first go to the modifier stack display and click the plus-sign icon next to the MultiRes modifier. This opens up its hierarchy, which consists of the single Vertex sub-object level. Next, click the Vertex entry. The MultiRes vertices appear on the mesh as blue dots. You can select these using any standard interactive method, but you cannot transform them.

Important: After selecting MultiRes sub-object vertices with Maintain Base Vertices turned on, re-generate the mesh before changing the vertex resolution.

In the following illustration, the clown started out as a high-resolution mesh. All of the MultiRes vertices in the right half were selected, Maintain Base Vertices was turned on, and then the vertices were reduced.

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

Example:

modPanel.addModToSelection(MultiRes())

$.modifiers[#MultiRes].Vertex_Count = 482

$.modifiers[#MultiRes].Vertex_Percentage = 100

$.modifiers[#MultiRes].Vertex_Percentage = 99

$.modifiers[#MultiRes].Vertex_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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Vortex - superclass: SpacewarpObject

Vortex - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID: #(217851359, 1867456353)

The Vortex space warp applies a force to particle systems, spinning them through a whirling vortex, and then moving them down a long, thin spout or vortex well. Vortex is useful for creating black holes, whirlpools, tornadoes, and other funnel-type objects.

The space warp settings let you control the vortex shape, the well characteristics, and rate and range of particle capture. The shape of the vortex is also affected by particle system settings, such as speed.

Constructor

Vortex ...

Properties

<Vortex>.'time on' Integer default: 0 -- integer; Time_On

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

<Vortex>.'time off' Integer default: 16000 -- animatable; integer; Time_Off

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

<Vortex>.axialstrength Float default: 0.1 -- animatable; float; Axial_Drop_Strength

Specifies how quickly particles move in the direction of the drop axis.

<Vortex>.axialrange Float default: 100.0 -- animatable; float; Axial_Range

The distance from the center of the Vortex icon, in system units, at which Axial Damping has its full effect. Takes effect only when Unlimited Range is turned off.

<Vortex>.axialfalloff Float default: 1000.0 -- animatable; float; Axial_Falloff

Specifies the distance beyond the Axial Range within which Axial Damping is applied. Axial Damping is strongest at the Range distance, decreases linearly out to the limit of the Axial Falloff, and has no effect beyond that. Takes effect only when Unlimited Range is turned off.

<Vortex>.axialdamping Float default: 5.0 -- animatable; percentage; Axial_Damping; Controller Scaling: (1 : 100.0)

Controls the degree to which particle motion parallel to the drop axis is restrained per frame. Default=5.0. Range=0 to 100.

For subtle effects, use values of less than 10%. For more overt effects, try using higher values that increase to 100% over the course of a few frames.

<Vortex>.rotationstrength Float default: 0.5 -- animatable; float; Orbital_Speed_Strength

Specifies how quickly the particles rotate.

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

The distance from the center of the Vortex icon, in system units, at which Orbital Damping has its full effect. Takes effect only when Unlimited Range is turned off.

<Vortex>.rotationfalloff Float default: 1000.0 -- animatable; float; Orbital_Falloff

Specifies the distance beyond the Orbital Range within which Orbital Damping is applied. Orbital Damping is strongest at the Range distance, decreases linearly out to the limit of the Orbital Falloff, and has no effect beyond that. Takes effect only when Unlimited Range is turned off.

<Vortex>.rotationdamping Float default: 5.0 -- animatable; percentage; Orbital_Damping; Controller Scaling: (1 : 100.0)

Controls the degree to which orbital particle motion is restrained per frame. Smaller values produce a wide spiral, while larger values produce a thin spiral. Default=5.0. Range=0 to 100.

<Vortex>.radialstrength Float default: 0.5 -- animatable; float; Radial_Pull_Strength

Specifies the distance from the drop axis at which the particles rotate.

<Vortex>.radialrange Float default: 100.0 -- animatable; float; Radial_Range

The distance from the center of the Vortex icon, in system units, at which Radial Damping has its full effect. Takes effect only when Unlimited Range is turned off.

<Vortex>.radialfalloff Float default: 1000.0 -- animatable; float; Radial_Falloff

Specifies the distance beyond the Radial Range within which Radial Damping is applied. Radial Damping is strongest at the Range distance, decreases linearly out to the limit of the Radial Falloff, and has no effect beyond that. Takes effect only when Unlimited Range is turned off.

<Vortex>.radialdamping Float default: 5.0 -- animatable; percentage; Radial_Damping; Controller Scaling: (1 : 100.0)

Controls the degree to which Radial Pull is restrained per frame. Default=5.0. Range=0 to 100.

<Vortex>.taperstrength Float default: 100.0 -- animatable; float; Taper_Length

Controls the shape of the vortex. Low values create a vortex with a wide, flared mouth, while high values create a vortex with nearly vertical sides. Default=100. Range=1.0 to 4.0.

<Vortex>.tapershape Float default: 1.0 -- animatable; float; Taper_Curve

Controls the length of the vortex, as well as its shape. Lower settings give you a "tighter" vortex, while higher settings give you a "looser" vortex. Default=100.

<Vortex>.direction Integer default: 0 -- radio button number

Determines whether particles rotate clockwise or counterclockwise.

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

When on, Vortex exerts full damping strength over an unlimited range. When off, the Range and Falloff settings take effect.

<Vortex>.iconsize Float default: 10.0 -- float; Icon_Size

Specifies the size of the icon.

Example:

Vortex 'time on':0 'time off':16000 axialstrength:0.1 axialrange:100 axialfalloff:1000 axialdamping:5 rotationstrength:0.5 rotationrange:100 rotationfalloff:1000 rotationdamping:5 radialstrength:0.5 radialrange:100 radialfalloff:1000 radialdamping:5 taperstrength:100 tapershape:1 direction:0 rangeless:on pos:[32.5437,-58.2321,0] isSelected:on iconSize:25.8103

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXKeyArray Values

MAXKey Common Properties, Operators, and Methods

Working with MAXKey Values


Class and Object Inspector Functions Enhanced

Topic: version 4 MAXScript Language Improvements/ Object Inspector Functions Enhanced

Interfaces

Core Interfaces

Other Interfaces

showInterfaces {<maxwrapper> | <maxclass> | node} [ to:<stream> ]

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

and <maxclass> is the 3ds max class to be inspected

and the optional to:<stream> keyword argument specifies a Stream Value to output the display to.

When the 3ds max entity specified is a node (for example $box01), this function only displays the Interfaces of the base object. It does not show the Interfaces of the transform controllers, modifiers, or materials applied to the object. To display the Interfaces for one of these objects, that object must be specified as the 3ds max entity.

As a special case, you can also call showInterfaces on the superclass 'Node' to display the interfaces that are common to all scene nodes.

The display of interface information is divided into three sections: Properties, Methods, and Actions. In the Properties section, each property exposed by the interface is listed along with its data type or enumeration values and whether the property can be read and written to. In the Methods section, each method is listed along with its return type and its argument list. The value type for each argument is shown. If the return type of is shown as <void>, the method returns a value of 'ok'. Methods that are used by Actions are commented as such. These methods typically require that the object be selected and active in the appropriate command panel. In the Actions section, each Action is listed along with its category and action description as shown in the Customize User Interface dialog, and the shortcut keys, if any, assigned to the Action.

Note: Refer to the MAXScript Class Hierarchy 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

.boneFreezeLength : boolean : Read|Write

.boneScaleType : enum : Read|Write

boneScaleType enums: {#scale|#squash|#none}

.stretchTM : matrix3 by value : Read

.boneAxis : enum : Read|Write

boneAxis enums: {#X|#Y|#Z}

.boneAxisFlip : boolean : Read|Write

.primaryVisibility : boolean : Read|Write

.secondaryVisibility : boolean : Read|Write

.applyAtmospherics : boolean : Read|Write

.vertexColorType : enum : Read|Write

vertexColorType enums: {#color|#illum|#alpha|#color_plus_illum}

.showVertexColors : integer : Read|Write

.shadeVertexColors : integer : Read|Write

.handle : DWORD : Read

Methods:

<void>setBoneEnable <boolean>onOff <time>time

<void>realignBoneToChild()

<void>resetBoneStretch()

Actions:

OK

See also

Core Interfaces

Other Interfaces


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, scripted atmospheric or scripted material. 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

Interface: NetRender


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

BMP Interfaces

Portable_Network_Graphics Interfaces

JPEG Interfaces

Targa Interfaces


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

Plug In Manager

Plug-in_Manager Interfaces

Visual 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

Interface: NetRender


Two New Scripted Pug-in Superclasses

Two 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

Scripted Manipulators


Definition Constructs Can Include Global Variable Declarations At Top Level

Topic: version 4 MAXScript Language Improvements/Globals and Locals

All the major definition constructs in MAXScript (such as utility, rollout, macroScript, rcmenu, tool, plug-in, etc.) can now include global variable declarations at the top-level within them.

Example:

rollout foo "foo"

(

local a, b = undefined, c

global d, e = 3 -- now possible

spinner bar "Bar"

checkBox baz "Baz: "

on bar changed do ...

)

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


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

Scope of Variables


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

Material Editor Access

Material Level Show-in-viewport State


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

BitmapTexture : TextureMap

BMP, PNG, JPEG and TGA I/O Interfaces

Material Editor Access

Accessing The Material Editor Active Slot

Material Level Show-in-viewport State

showTextureMap() Function


BMP, PNG, JPEG, and TGA I/O Interfaces

Topic: version 4 MAXScript Language Improvements / Material Editor, Material and Textures

BMP Interfaces

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:

This is a function published interface for png I/O that provides access to the type of image to be saved.

JPEG interfaces:

This is a function published interface for jpeg I/O that provides access to the type of image to be saved.

Targa interfaces:

This is a function published interface for tga I/O that provides access to the type of image to be saved.


Material Editor Access

Topic: version 4 MAXScript Language Improvements / Material Editor, Material and Textures

Interface available for Texmap and Mtl, Interface: medit.

<maxObject>GetCurMtl()

This method returns a material base pointer for the current material.

<void>SetActiveMtlSlot <index>slot <boolean>forceUpdate

<index>slot

The material slot index.

<boolean>forceUpdate

Set this to TRUE to update the slot contents.

This method allows you to set the active material slot.

<index>GetActiveMtlSlot()

This method returns the index of the active material slot.

<void>PutMtlToMtlEditor <maxObject>mtl <index>slot

<maxObject>mtl

The material you want to put.

<index>slot

The index of the material slot you wish to put the material into.

This method allows you to put the specified material to the specified material editor slot.

<maxObject>GetTopMtlSlot <index>slot

<index>slot

The index of the material slot for which you wish to obtain the material.

This method returns a pointer to the material base from the specified slot.

<boolean>OkMtlForScene <material>mtl

<material>mtl

The pointer to the material.

This method is available in release 4.0 and later only. Before assigning material to scene, call this to avoid duplicate names.

<void>UpdateMtlEditorBrackets()

This method is available in release 3.0 and later only. It 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

BitmapTex Reload and viewImage


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

i-drop - drag and drop


showTextureMap() function

Topic: version 4 MAXScript Language Improvements / Material Editor, Material and Textures

The showTextureMap() function has been updated to allow control over material level texture showing in the viewport. The full form is now:

showTextureMap <material> [<texmap>] <boolean>

If the optional <texmap> is supplied, it must be a direct subtexture of the supplied material and its show-in-viewport state will be set on or off according to the <boolean> argument. If only a <material> is supplied, its show-in-viewport state will be set by the <boolean> argument.

Example:

showTextureMap $foo.material on

showTextureMap $foo.material $foo.material.diffusemap off

Note: Mapping coordinates aren't explicitly enabled for the objects at creation time. When a script is run in the Listener, using 'showTextureMap' is indirectly turning mapping coordinates on. This happens during the scene redraw which happens after each line is executed, if needed. If a script is run from a script editor, or if you put parenthesis around a script, no scene redraw is performed until the entire script is run. Since no redraw is performed, no mapping coordinates exist on the object when the script tries to access them. Solutions: explicitly perform a scene redraw [redrawViews()] after 'showTextureMap', or explicitly turn on mapping coordinates for the object.

See also

Material Editor

TextureMap Common Properties, Operators, and Methods

Material Level Show-in-viewport State

Accessing The Material Editor Active Slot

Material Editor Access


Angle UI element

Topic: version 4 MAXScript Language Improvements /User Interface

Angle <name> [caption] [color:<color>] [degrees:<float>] [bitmap:<bitmap>] [diameter:<float>] [StartDegrees:<integer>] [StartRadians:<integer>] [dir:<#cw|#ccw>] [range:<point3>]

Properties

<Angle>.color color default:(color 0 0 255)

Angle fill in color. Setting the color turns off the Bitmap fill.

<Angle>.bitmap Bitmap default:undefined

Angle fill in Bitmap. Setting the Bitmap turns off the color fill.

<Angle>.diameter Integer default:64

The full diameter of the control, .width and .height are synonymous to this.

<Angle>.degrees Float default:0.0

Current angle in degrees.

<Angle>.radians Float default:0.0

Current angle in radians.

<Angle>.StartDegrees

<Angle>.StartRadians

<Angle>.dir

<Angle>.range

Events

on <Angle> changed <arg> do <expr>

Called when the angle is being changed. <arg> is the current degrees value.

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

Rollout User-Interface Controls Types

Rollout User-Interface Controls Common Layout Parameters

Rollout User-Interface Controls Common Properties


CreateDialog

CreateDialog has been enhanced. The prototype is now:

CreateDialog <Rollout> [<height> <width> <position_x> <position_y>]\

[pos:<Point2>] [width:<integer>] [height:<integer>] \

[bgcolor:<color>] [fgcolor:<color>] \

[bitmap:<bitmap>] {bmpstyle:<bmpstyle> \

[menu:<RCMenu>] [style:<array>] [modal:<boolean>]

Modal dialog support added to MAXScript scripter dialogs, those created with the CreateDialog() function. A new keyword argument can be supplied to the CreateDialog() function, modal:<boolean>, to control whether the dialog is modal or not. Defaults to modal:false.

A modal dialog ignores all user interactions except those within the dialog. Call DestroyDialog() to close it, presumably in a scripted OK button, or the like. The user can also close a modal scripted dialog by hitting the <escape> key.

Parameters

<Rollout>

The rollout definition to create the dialog from.

[pos:<Point2>] -- default:dialog will center within MAX.

Placement of the upper left corner of the dialog relative to the upper left corner of the screen.

[width:<integer>] -- default:200

Width of the dialog box.

[height:<integer>] -- default:dynamic on control extents

Height of the dialog box.

[bgcolor:<color>] -- default:(<system button color>)

Background color of the dialog.

[fgcolor:<color>] -- default:(color 0 0 0)

Forground color of the dialog (static text color)

[bitmap:<bitmap>] -- default:undefined

Background bitmap for the dialog.

[bmpstyle:<key>] -- default:#bmp_center

The way that the background bitmap is displayed.

Can be one of the following:

#bmp_center

#bmp_tile

#bmp_stretch

[menu:<RCMenu>] -- default:undefined

Menu that will apear in the title bar area of the dialog.

[style:<array>] -- default:#(#style_titlebar, #style_border, #style_sysmenu)

Array of style flags, can be one or more of the following:

#style_border: Creates a window with a double border but no title.

#style_titlebar: Creates a dialog with a title bar.

#style_toolwindow: Creates a tool window, which has a title bar and is intended to be used as a floating toolbar. A tool window has a title bar that is shorter than a normal title bar, and the window title is drawn using a smaller font.

#style_resizing: Creates a window with a thick frame that can be used to size the window.

#style_minimizebox: Creates a window that has a minimize button.

#style_maximizebox: Creates a window that has a maximize button.

#style_sysmenu: Creates a window that has a window menu in its title bar.

#style_sunkenedge: Specifies that a window has a 3D look, in the form of a border with a sunken edge.

Note: If the style keyword parameter is not specifed, the default styles of #style_titlebar, #style_border, #style_sysmenu are used.

Events

on <Rollout> open do

Called when the dialog is opening.

on <Rollout> close do

Called when the dialog is closing.

on <Rollout> moved <Point2> do

Called when the dialog is being moved.

on <Rollout> resized <Point2> do

Called when the dialog is being resized.

on <Rollout> mousemove <Point2> do

Called when the mouse is being moved within the dialogs client area.

on <Rollout> lbuttondown <Point2> do

Called when the left mouse button is pressed down within the dialog.

on <Rollout> lbuttonup <Point2> do

Called when the left mouse button is released.

on <Rollout> lbuttondblclk <Point2> do

Called when left mouse button is double clicked within the dialog.

on <Rollout> mbuttondown <Point2> do

Called when middle mouse button is pressed down within the dialog.

on <Rollout> mbuttonup <Point2> do

Called when the middle mouse button is released.

on <Rollout> mbuttondblclk <Point2> do

Called when middle mouse button is double clicked within the dialog.

on <Rollout> rbuttondown <Point2> do

Called when right mouse button is pressed down within the dialog.

on <Rollout> rbuttonup <Point2> do

Called when the right mouse button is released.

on <Rollout> rbuttondblclk <Point2> do

Called when right mouse button is double clicked within the dialog.

Note: The <Point2> value passed to the event handlers is the position of the mouse within the dialog client window. A value of [0,0] corresponds to the top left corner of the clientwindow. The top left corner of the dialog window

Associated Methods

<Point2> GetDialogPos <Rollout>

Returns the position of the Dialog built from the rollout relative to the upper left corner of the screen in Point2 format.

SetDialogPos <Rollout> <Point2>

Sets the position of the dialog built from the rollout relative to the upper left corner of the screen.

Rollout: The rollout used to build the Dialog.

Point2: Position where the Dialog is placed.

See also

DestroyDialog

GetDialogPos and SetDialogPos

MAXScript Dialogs and Rollout Floaters as Extended viewports


Curve Control

Topic: version 4 MAXScript Language Improvements /User Interface

You can create CurveControl's in rollouts by using the following:

CurveControl <name> [ <caption> ] [ visible: <boolean> ] [ numCurves: <integer> ] \ [ x_range: <point2> ] [ y_range: <point2> ] [ zoomValues: <point2> ] \ [ scrollValues: <point2> ] [ displayModes: <bitarray> ] \ [ commandMode: <#move_xy | #move_x | #move_y | #scale | #corner | bezier> ] \ [ uiFlags: <array_of_ui_flags> ] \ [ rcmFlags: <array_of_rcm_flags> ] [ asPopup:<boolean> ]

uiFlags:

Any combination of the following flags:

#drawBG, #drawgrid, #upperToolbar, #showReset, #scrollBars, #constrainY,#xvalue

rcmFlags:

Any combination of the following flags:

#move_xy, #move_x, #move_y, #scale, #corner, #bezier, #delete, #all

<curvecontrol>.visible : Boolean

<curvecontrol>.x_range : Point2

<curvecontrol>.y_range : Point2

<curvecontrol>.displayModes : BitArray

<curvecontrol>.commandMode : Name

<curvecontrol>.zoomValues : Point2

Note: The following will automatically perform a zoom extents all:

zoom <curvecontrol> #all

<curvecontrol>.scrollValues : Point2

<curvecontrol>.curves : Array, read-only

Returns an array of curves of type MAXCurve

Events

In the following events <ci> represents the active Curve Index.

on <curvecontrol> selChanged <ci> <val> do <expr>

Sent when a point is selected or deselected. <val> is the number of points, which are selected.

on <curvecontrol> ptChanged <ci> <val> do <expr>

Sent when a point is changed, <val> is the index of the changed point

on <curvecontrol> tangentChanged <ci> <val> type do <expr>

Sent when a point's in or out tangent is changed, <val> is the index of the changed point type is #inTangent or #outTangent, depending on what changed.

on <curvecontrol> deleted <ci> <val> do <expr>

Sent when a point is deleted, val is the index of the deleted point.

on <curvecontrol> reset <ci> do <expr>

Sent when a curve is reset

ccCurve represents a single curve in a curve control

Properties

<ccCurve>.animatable : Boolean

<ccCurve>.color : Color

<ccCurve>.disabledColor : Color

<ccCurve>.width : Integer

<ccCurve>.disabledWidth : Integer

<ccCurve>.disabledStyle : Name

<ccCurve>.style : Name

These are the drawing styles for the curves, can be any one of the following:

#solid, #dash, #dot, #dashDot, #dashDotDot, #null, #insideFrame

<ccCurve>.lookupTableSize : Integer

This method sets the size of the Curve Control lookup table. The lookup table allows users of the Curve Control to easily speed up their value access. The default value for the lookup table size is 1000. Used when getValue() is called on the curve.

<ccCurve>.numPoints : Integer

<ccCurve>.points : Array, read-only

Returns a CurvePointsArray

Methods

getValue ccCurve <time_value> <float_x> [lookup:<false>]

Returns a Point2

isAnimated ccCurve <index>

Returns a Boolean value

getSelectedPts ccCurve

Returns a BitArray

setSelectedPts <ccCurve> <bitarray> [#select] [#deSelect] [#clear]

setPoint <ccCurve> <index> <ccpoint> [checkConstraints:<true>]

getPoint <ccCurve> <index>

insertPoint <ccCurve> <index> <ccpoint>

deletePoint <ccCurve> <index>

CurvePointsArray represents an array of curve points. CurvePointValue represents a curve point.

CurvePointValue represents a curve point, you create a curve point like:

ccPoint <pt_point2> <in_point> <out_point2> \ [bezier:<false>] [corner:<false>] [lock_x:<false>] [lock_y:<false>] \ [select:<false>] [end:<false>] [noXConstraint:<false>]

Properties

<ccpoint>.value : Point2

<ccpoint>.inTangent : Point2

<ccpoint>.outTangent : Point2

<ccpoint>.bezier : Boolean

<ccpoint>.corner : Boolean

<ccpoint>.lock_x : Boolean

<ccpoint>.lock_y : Boolean

<ccpoint>.selected : Boolean

<ccpoint>.end : Boolean

<ccpoint>.noXConstraint : Boolean

Example:

rollout uTestCurveControl "Curve Control"(

-- Curve control Properties

local ccProps = #(

#visible,

#numCurves,

#x_range,

#y_range,

#displayModes,

#zoomValues,

#scrollValues,

#commandMode)

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

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

(tab + "Curve%\n") i

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

Rollout User-Interface Controls Types

Rollout User-Interface Controls Common Layout Parameters

Rollout User-Interface Controls Common Properties


DestroyDialog

DestroyDialog <Rollout>

Closes a dialog box created with CreateDialog.

<Rollout>: The rollout used to build the dialog to close.

See also

CreateDialog

GetDialogPos and SetDialogPos


GetDialogPos and SetDialogPos

Point2 GetDialogPos <Rollout>

Returns the position of the Dialog built from the rollout relative to the upper left corner of the screen in Point2 format.

SetDialogPos <Rollout> <Point2>

Sets the position of the Dialog built from the rollout relative to the upper left corner of the screen.

<Rollout>: The rollout used to build the Dialog to set the position of.

<Point2>: Position where to place the Dialog.

See also

CreateDialog

DestroyDialog


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


GroupBox

GroupBox <name> [caption] [pos:<point2>] [width:<integer>] [height:<integer>]

Use the pos, width, and height properties to set the size.

Known bugs:

Group boxes have a line drawn through them when using bitmap backgrounds with CreateDialog. This is a problem with the windows groupbox control.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


HyperLink

HyperLink <name> [caption] [color:<color>] [hoverColor:<color>] [visitedColor:<color>] [address:<string>]

Properties

<HyperLink>.color Color default:(color 0 0 255)

Base color of the text.

<HyperLink>.hoverColor Color default:(color 0 255 255)

Color of text when mouse is over it.

<HyperLink>.visitedColor Color default:(color 0 0 192)

Color of text after you have used the link.

<HyperLink>.address String default:"http://www.discreet.com"

The string sent to ShellExecute

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


isActive

Topic: version 4 MAXScript Language Improvements /User Interface

isActive <atmos>

Returns true if the atmospheric is set to active; false otherwise

isActive <renderEffect>

Returns true if the render effect is set to active; false otherwise

See also

Atmospheric Effects Common Properties, Operators, and Methods

Render Effects Common Properties, Operators, and Methods


keyboard.escPressed

Topic: version 4 MAXScript Language Improvements /User Interface

keyboard const StructDef

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

3ds max System Globals


macroScript Localization Support for CUI and menu files

In order to make the menu and CUI files more easily localized, a keyword argument, InternalCategory:, 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.

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"
InternalCategory:"Tools" -- This is the new keyword

ToolTip:"Isolate Tool"
Icon:#("ViewPortNavigationControls",7)

When this macroScript is localized the Category would be translated, but the InternalCategory would not.


MAX Open & Save Dialogs

Topic: version 4 MAXScript Language Improvements /User Interface

<string> getMAXSaveFileName filename:<seed_filename_string>

Displays standard MAX file save dialog. Returns file name or value 'undefined' if canceled.

<string> getMAXOpenFileName filename:<seed_filename_string> dir:<seed_directory_string>

Displays standard MAX file open dialog. Returns file name or value 'undefined' if canceled.

See also

3ds max File Loading and Saving


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"

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.

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.

cui.expertModeOff() -- Turns expert mode on

cui.expertModeOff() -- Turns expert mode off

cui.getExpertMode() -- returns true of expert mode is on

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

maxOps

Interface: maxOps

Menu Manager

Interface: menuMan

3ds max System Globals


mouse.screenpos

mouse.screenpos

A read only variable to get the mouse position on the screen as a <point2> value. The coordinates are in pixel values.

See also

Mouse Cursors


mtlBrowser

Topic: version 4 MAXScript Language Improvements /User Interface

mtlBrowser const StructDef

mtlBrowser.browseFrom [#mtlLibrary | #mtlEditor | #activeSlot | #selected | #scene | #new]

Lets you set the Browse From: source for the modeless material browser.

See also

Miscellaneous Dialogs


PopupMenu

PopupMenu <RCMenu> [pos:<Point2>] [rollout:<Rollout>] [align:<key>]

This method will popup a menu anywhere on the screen.

<RCMenu>: Any RCMenu defined. It does not have to be registered.

[pos:<Point2>]: The point where to put the menu up, either relative to the Rollout or the screen. (Default:popup from current mouse position.)

[rollout:<Rollout>]: This will make the menu popup from a rollouts local coordinate system. Specifying undefined will popup the menu relative to the upper left corner of the screen. (Default:undefined)

[align:<key>]: Can be one of the following (default:#align_topleft):

#align_topleft

#align_topcenter

#align_topright

#align_bottomleft

#align_bottomcenter

#align_bottomright

#align_vcenterleft

#align_vcentercenter

#align_vcenterright

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


SetBackground Method

Topic: version 4 MAXScript Language Improvements /User Interface

Changed SetBackground to take a color in addition to a point3.

setBackGround [<time>] <color>

If the time value is not specified, the current MAXScript time is used.

getBackGround [<time>]

Gets method that parallels setBackGround method.

See also

Working with Atmospherics


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

on:<node>

Optionally specifies a scene object to track on. If you don't supply an object, the mouse tracks on the current active grid. Note that the object surface tracker uses the SDK function IntersectRay() which is not reliably implemented on all object types. Editable meshes always work OK, so you can convertToMesh() if needed.

prompt:"msg"

Displays the prompt message in the MAX status line

snap:#2D|#3D

Relevant when not tracking on an object surface (no on:<node> specified). If snap mode is on and #2D is supplied, snaps to snap points on grid, if #3D is specified snaps to any near snap point in space.

trackCallback:fn|#(fn,arg)

Is where you specify the function to be called as the mouse is dragged over the active grid or object surface. You can specify it is a single function or a function and an argument value in a two element array. The latter form is useful if you have a common callback function for many tasks and want to send in a parameter to control its operation for a particular use. The function you give must be of the following form:

fn callback_fn msg ir obj faceNum shift ctrl alt = ...

in other words, a scripted function of 7 arguments. While the tracking is going on, it is called whenever a mouse action occurs, such as a button click or a drag, etc.

The 'msg' argument is a message code that indicates what kind of action occurred, and can be one of:

#freeMove - means the mouse is moved without a button being pressed

#mousePoint - means the left mouse button has just been pressed

#mouseMove - means the mouse is being dragged with the left button down

#mouseAbout - means the right mouse button was clicked, normally meaning cancel

'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.

'shift', 'ctrl' and 'alt'

True or false depending on the down or up state of the <shift>, <ctrl> and <alt> keys on the keyboard.

The function should return the special value #continue to continue tracking or any other value to halt tracking. That value then becomes the result of the original mouseTrack() call.

See also

Rollout User-Interface Controls


snapMode

Topic: version 4 MAXScript Language Improvements /User Interface

snapMode const StructDef

snapMode.active

Lets you get and set a Boolean value defining the Snap toggle state - on (true) or off (false).

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.

See also

3ds max System Globals


Spinner UI Item setKeyBrackets

Topic: version 4 MAXScript Language Improvements /User Interface

A new parameter has been added to spinner UI items, setKeyBrackets, which can be set to true (on) or false (off) to turn on and off the red keyframe brackets that signal a keyframe is present for animated parameters. This allows you to simulate keyframe notification in scripted rollouts by setting this spinner property on or off, most likely in a time change callback function. You can set this as a parameter on a spinner definition,

spinner ... setKeyBrackets:<boolean> ...

or via property assignment,

<spinner>.setKeyBrackets = <boolean>

See also

Spinner

Rollout User-Interface Controls

Rollout User-Interface Controls Types

Rollout User-Interface Controls Common Layout Parameters

Rollout User-Interface Controls Common Properties


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

Rollout User-Interface Controls

Rollout User-Interface Controls Types

Rollout User-Interface Controls Common Layout Parameters

Rollout User-Interface Controls Common Properties


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


Undo/Redo Dropdown Labels

MAXScript now provides some control over the labels displayed in the MAX undo/redo dropdown list for undoable MAXScript operations. This is an improvement to just displaying "MAXScript" in all cases, as it did in prior versions.

Any undoable macroScript execution, such as via a toolbar button, menu item, hotkey or quad-menu item, will now be displayed in the undo/redo list with the name of the macroScript.

The 'undo on' context prefix now accepts an optional string literal (text in double quotes) after the 'undo' keyword, which will be used as the label for the undo block in the MAX undo/redo lists.

Syntax

undo ["undo_item_label" | label:<string_operand>] <bool_expr> <expr>

where "undo_item_label" must be a string literal, but <string_operand> evaluates to a string at runtime.

Example:

rollout test "test"

(

local undoString = "Button Press"

local buttonPress = 0

button b "press me"

on b pressed do with undo label:(undoString + (buttonPress +=1) as string) on box()

)

createdialog test

Example:

undo "add background" on

(

...

)

This example 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

Sticky Contexts


Zoom to Bounds

Topic: version 4 MAXScript Language Improvements /User Interface

ZoomToBounds zooms the current or selected viewport to a bounding region.

Viewport.ZoomToBounds <A_Point3> <B_Point3> <All_Bool>

A_Point3

B_Point3

These values define the bounding region to zoom to.

All_Bool

When true, all viewports are zoomed. When false, only the selected viewport is zoomed.

See also

viewport const StructDef


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

Rollout Systems 'category' Mechanism

Rollout User-Interface Controls

Rollout User-Interface Controls Types

Rollout User-Interface Controls Common Layout Parameters

Rollout User-Interface Controls Common Properties

Visual 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

See also

ActiveX Controls in MAXScript Rollouts


Rollout .Controls Property

Topic: version 4 MAXScript Language Improvements / User Interface/ Command Panels and Rollout Pages

<rollout>.controls

This property returns an array of all the controls in the rollout.

Example:

for c in foo.controls do c.enabled = false

Foo is a rollout.

See also

Rollout User-Interface Controls

Rollout User-Interface Controls Types

Rollout User-Interface Controls Common Properties

Rollout User-Interface Controls Common Layout Parameters


Rollout Systems 'category' Mechanism

Topic: version 4 MAXScript Language Improvements / User Interface/ Command Panels and Rollout Pages

You can control the grouping of rollups for a plug-in by supplying a category:<integer> header parameter, before the opening parenthesis of the rollout body.

Example:

rollout foo "Frabulator" category:3

(

....

)

Category number orders the rollouts.

See also

Rollout User-Interface Controls

Rollout User-Interface Controls Types

Rollout User-Interface Controls Common Properties

Customize The Order of Rollup Pages

Interface: cmdPanel

Rollout User-Interface Controls Common Layout Parameters

Visual MAXScript


Definitions for MAXScript internal organization

MAXScriptFunction

Const Generic

Const MappedGeneric

Const NodeGeneric

Const Primitives

Const StructDef

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 3ds max - these classes will be created in MAXScript as Const MAXClass.

See also

MAXScriptFunction List

Const Generic

Const MappedGeneric

Const NodeGeneric

Const Primitives

Const StructDef

Const Class


MAXScriptFunction List

AddConstraint Functions for use with Constraint Assignments

AddConstraintTargets Controller Functions for use with Constraint Assignments

AddListController Controller Functions for use with Constraint Assignments

AddMod

ApplyOperation ApplyOperation function

ChangeSystemColorsAnimateOff

ChangeSystemColorsAnimateOn

help

KindOfRenderElement

RElements2cws

SaveQuadClr

SetActiveController Controller Functions for use with Constraint Assignments

Show Apropos" and "ShowProperties" and now "Help" and "Show"

TurnToSeq

See also

Definitions for MAXScript internal organization


Const Class

ActionPredicate

ActiveXControl ActiveX Controls in MAXScript Rollouts - in example with def

AngleAxis

AngleControl

Array

ArrayParameter

AtmosphericClass MAXScript Class Hierarchy

BigMatrix BigMatrix Values - in example with def, Basic Data Values, Const Generic, Const MappedGeneric, MAXScript Class Hierarchy

BigMatrixRowArray BigMatrix Values - in example with def, MAXScript Class Hierarchy

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

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

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

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

UserGeneric

value

ValueRef

VertexSelection

WindowStream

XRefScene

See also

Definitions for MAXScript internal organization


Const Generic

abs Number Values - in example with def, Camera Common Properties, Operators, and Methods - in example, Scripted Geometry Plug-ins - in example, Scripted Shape Plug-ins - in example, Scripted SimpleObject Plug-ins - in example, The Return Expression - in example, Time Values

addMultiplierCurve Controller Ease and Multiplier Curve Functions - in example with def

addNewNoteKey MAXNoteKeyArray Values - in example MAXNoteKeyArray_Value, MAXNoteKey Values - in example MAXNoteKey_Values, Working with Note Tracks- in example Working_with_Note_Tracks

addPluginRollouts Scripted Plug-in Methods Scripted_Plugin_Methods

AllowBlending PhyContextExport Values

append

appendCurve NURBS1RailSweepSurface : NURBSSurface, NURBS2RailSweepSurface : NURBSSurface, NURBSMultiCurveTrimSurface : NURBSSurface, NURBSULoftSurface : NURBSSurface,

appendCurveByID NURBS1RailSweepSurface : NURBSSurface, NURBS2RailSweepSurface : NURBSSurface, NURBSMultiCurveTrimSurface : NURBSSurface, NURBSULoftSurface : NURBSSurface

appendGizmo Atmospheric Effects Common Properties, Operators, and Methods, Working with Atmospherics - example

appendObject Modifying Existing NURBS Objects, Creating New NURBS Objects - in example, NURBSSet : Value

appendUCurve NURBSUVLoftSurface : NURBSSurface

appendUCurveByID NURBSUVLoftSurface : NURBSSurface

appendVCurve NURBSUVLoftSurface : NURBSSurface

appendVCurveByID NURBSUVLoftSurface : NURBSSurface

applyEaseCurve Controller Ease and Multiplier Curve Functions - in example with def

attach

buildTVFaces Editable_Mesh : GeometryClass and TriMesh : Value, Working with Editable Meshes – in example

buildVCFaces Editable_Mesh : GeometryClass and TriMesh : Value

canConvertTo Node Common Properties, Operators, and Methods, NURBS Node Properties and Methods

classOf

clear

clearAllAppData Access to MAXWrapper AppData

clearCacheEntry

clearProdTess NURBSSet : Value, NURBSSurface : NURBSObject

clearViewTess NURBSSet : Value, NURBSSurface : NURBSObject

close

closeU NURBSCVSurface : NURBSSurface, NURBSPointSurface : NURBSSurface

closeV NURBSCVSurface : NURBSSurface, NURBSPointSurface : NURBSSurface

collapseface Editable_Mesh : GeometryClass and TriMesh : Value

composite

Conjugate Quat Values

contains

ConvertToRigid PhyContextExport Values

createInstance MAXWrapper Common Properties, Operators, and Methods, Scripted Manipulator- in example, Scripted Manipulators - in example, Scripted SimpleObject Plug-ins - in example with def

crop bgndRenderElement - superclass: MAXObject - in example, BitmapTex fnReload and fnCrop, bitmapTex interfaces: - in example, BitmapTexture : TextureMap

cross

defaultVCFaces Editable_Mesh : GeometryClass and TriMesh : Value

deleteAppData Access to MAXWrapper AppData

deleteface Editable_Mesh : GeometryClass and TriMesh : Value

deleteGizmo Atmospheric Effect Types

deleteItem

deleteKey Attachment : PositionController, Biped Keys, Controller Key Functions, MAXKeyArray Values

deleteMultiplierCurve Controller Ease and Multiplier Curve Functions

deleteNoteKey MAXNoteKeyArray Values, Working with Note Tracks - in example

deleteNoteKeys MAXNoteKeyArray Values, Working with Note Tracks - in example

deleteObjects NURBSSet : Value

deleteTracker

deletevert Editable_Mesh : GeometryClass and TriMesh : Value

deselectKey Controller Key Functions

detachFaces

detachVerts

disconnect Interface: paramWire - in example

displacementToPreset Editable_Mesh : GeometryClass and TriMesh : Value

display

distance

dot

empty

eof

evalPos NURBSCurve : NURBSObject, NURBSSurface : NURBSObject,

evalTangent NURBSCurve : NURBSObject

evalUTangent NURBSSurface : NURBSObject

evalVTangent NURBSSurface : NURBSObject

execute

exp Number Values, Mathematical Operations in MAXScript, Quat Values - in example with def

exprForMAXObject Mesher - superclass: GeometryClass

extrudeface Editable_Mesh : GeometryClass and TriMesh : Value, Scripted SimpleObject Plug-ins

filepos FileStream Values, StringStream Values

findItem

findPattern

findString String Values, Function Parameters, Pickbutton

flagChanged XRefScene Values

flush FileStream Values, StringStream Values, Turning On the Listener Log

getAfterORT Controller Out-Of-Range Functions Controller_Key_Reducer

getAppData Access to MAXWrapper AppData

getBeforeORT Controller Out-Of-Range Functions

getChannel Bitmap Values

getChannelAsMask Bitmap Values, Scripted RenderEffect Plug-ins - in example

getCurve NURBS1RailSweepSurface : NURBSSurface, NURBS2RailSweepSurface : NURBSSurface, NURBSULoftSurface : NURBSSurface

getCurveID NURBS1RailSweepSurface : NURBSSurface, NURBS2RailSweepSurface : NURBSSurface, NURBSULoftSurface : NURBSSurface

getCurveStartPoint NURBS1RailSweepSurface : NURBSSurface, NURBS2RailSweepSurface : NURBSSurface

getCV NURBSControlVertex : NURBSObject, NURBSCVCurve : NURBSCurve, NURBSCVSurface : NURBSSurface

getDisplacementMapping Editable_Mesh : GeometryClass and TriMesh : Value

getEdge NURBSBlendSurface : NURBSSurface, NURBSNBlendSurface : NURBSSurface

getEdgeVis Editable_Mesh : GeometryClass and TriMesh : Value

getface Editable_Mesh : GeometryClass and TriMesh : Value, Working with Editable Meshes

getFaceMatID Editable_Mesh : GeometryClass and TriMesh : Value

getFaceNormal Editable_Mesh : GeometryClass and TriMesh : Value

getFaceSmoothGroup Editable_Mesh : GeometryClass and TriMesh : Value

getFlip NURBS1RailSweepSurface : NURBSSurface, NURBS2RailSweepSurface : NURBSSurface, NURBSULoftSurface : NURBSSurface, path interfaces:, Path_Constraint interfaces:

getFlipTrim NURBSFilletSurface : NURBSSurface

getGenerateUVs NURBSSurface : NURBSObject

getGizmo Atmospheric Effects Common Properties, Operators, and Methods

getIndexedPixels Bitmap Values

getKey

getKeyIndex Controller Key Functions

getKey

getKnot NURBSCVCurve : NURBSCurve

getModContextBBoxMax Modifier Common Properties, Operators, and Methods, Modifier Sub-Object Transform Properties, Node Common Properties, Operators, and Methods

getModContextBBoxMin Modifier Common Properties, Operators, and Methods, Modifier Sub-Object Transform Properties, Node Common Properties, Operators, and Methods, Scripting Vertex and Control Point Animation

getModContextTM Modifier Common Properties, Operators, and Methods, Modifier Sub-Object Transform Properties, Node Common Properties, Operators, and Methods

getMultiplierValue Controller Ease and Multiplier Curve Functions

GetNode Biped and Physique - in example

getnormal Editable_Mesh : GeometryClass and TriMesh : Value, Scripted Manipulators

getNoteKeyIndex Notetrack Values

getNoteKeyTime MAXNoteKeyArray Values, Notetrack Values

getNumCPVVerts Editable_Mesh : GeometryClass and TriMesh : Value

getNumFaces Editable_Mesh : GeometryClass and TriMesh : Value

getNumTVerts Editable_Mesh : GeometryClass and TriMesh : Value

getNumVerts Editable_Mesh : GeometryClass and TriMesh : Value, Patches

getObject Patches

GetOffsetVector Biped and Physique - in example

getParent NURBSBlendSurface : NURBSSurface, NURBSFilletSurface : NURBSSurface, NURBSMultiCurveTrimSurface : NURBSSurface, NURBSNBlendSurface : NURBSSurface, Trackviews

getParentID NURBSBlendSurface : NURBSSurface, NURBSFilletSurface : NURBSSurface, NURBSMultiCurveTrimSurface : NURBSSurface, NURBSNBlendSurface : NURBSSurface

getPixels Bitmap Files, Scripted RenderEffect Plug-ins

getPoint NURBSIndependentPoint : NURBSPoint, NURBSPointCurve : NURBSCurve, NURBSPointSurface : NURBSSurface, NURBSTexturePoint : NURBSObject, NURBSTextureSurface : Value, Curve Control, Scripted Manipulators

getProdTess NURBSSet : Value, NURBSSurface : NURBSObject

getPropNames Class and Object Inspector Functions, Array Values –in example, ActiveX Controls in MAXScript Rollouts, Scripted Manipulators –in example

getRadius NURBSFilletSurface : NURBSSurface

getSeed NURBSFilletSurface : NURBSSurface

getSplitMesh Editable_Mesh : GeometryClass and TriMesh : Value

getSubAnim Indexed Access to Animatable Properties in 3ds max Objects

getSubAnimName Indexed Access to Animatable Properties in 3ds max Objects, Subanim Indexing Operator, [], on 3ds max Objects Now Takes Subanim Names

getSubAnimNames Indexed Access to Animatable Properties in 3ds max Objects, Subanim Indexing Operator, [], on 3ds max Objects Now Takes Subanim Names

getSubdivisionDisplacement Editable_Mesh : GeometryClass and TriMesh : Value

getTextureSurface NURBSSurface : NURBSObject, NURBSTextureSurface : Value

getTextureUVs NURBSSurface : NURBSObject

getTiling NURBSSurface : NURBSObject

getTilingOffset NURBSSurface : NURBSObject

getTimeRange Controller Time Functions

getTracker

getTrimSurface NURBSFilletSurface : NURBSSurface

getTVert Editable_Mesh : GeometryClass and TriMesh : Value, Node Common Properties, Operators, and Methods –in example

getTVFace Editable_Mesh : GeometryClass and TriMesh : Value, Node Common Properties, Operators, and Methods –in example

getUCurve NURBSUVLoftSurface : NURBSSurface

getUCurveID NURBSUVLoftSurface : NURBSSurface

getUKnot NURBSCVSurface : NURBSSurface

getVCFace Editable_Mesh : GeometryClass and TriMesh : Value

getVCurve NURBSUVLoftSurface : NURBSSurface

getVCurveID NURBSUVLoftSurface : NURBSSurface

getVert Editable_Mesh : GeometryClass and TriMesh : Value, Patches, Script Controllers –in example

getvertcolor Editable_Mesh : GeometryClass and TriMesh : Value

getVertexInterface PhyBlendingRigidVertex Values, PhyContextExport Values, PhyRigidVertex Values, Biped and Physique –in example

getViewTess NURBSSet : Value, NURBSSurface : NURBSObject

getVKnot NURBSCVSurface : NURBSSurface

getWeight PhyBlendingRigidVertex Values, Class and Object Inspector Functions –in example, LookAt_Constraint - superclass: RotationController, LookAt_Constraint interfaces:, Orientation Constraint Controller, Path_Constraint interfaces:, Position Constraint, Position_Constraint interfaces:

gotoFrame Bitmap Values

invalTrack

Inverse Matrix3 Values, Using Node Transform Properties –in example

invert BigMatrix Values, VolumeSelect : Modifier, Volume_Light : Atmospheric, Volume_Fog : Atmospheric

isEmpty Box2 Values, Coercion of bitArray to array and integer arrays to bitArrays

isIdentity Matrix3 Values, Quat Values

isKeySelected Controller Key Functions, CS3Tools.cui Tutorial –in example

isKindOf Working with Values, ObjectSet Values –in example, Structure Inherited Methods

join BitArray Values, Array Values

length

LnDif Quat Values

loadFrames

LogN Quat Values

merge XRefScene Values, Zip-file Script Packages, NURBSSet : Value

moveKey Controller Key Functions

normalize Quat Values, Point3 Values, Point2 Values, Scripted Plug-in Methods –in example

numEaseCurves Controller Ease and Multiplier Curve Functions

numKeys Controller Key Functions

numMultiplierCurves Controller Ease and Multiplier Curve Functions

numSelKeys Controller Key Functions

perspectiveMatch

QCompA Quat Values

qorthog Quat Values

random Number Values, Node Common Properties, Operators, and Methods

readChar FileStream Values, StringStream Values

readChars FileStream Values, StringStream Values

readDelimitedString FileStream Values, StringStream Values

readExpr MAXScript System Globals, Value Common Properties, Operators, and Methods, FileStream Values, StringStream Values

readLine FileStream Values, StringStream Values

readValue FileStream Values, StringStream Values, Access to MAXWrapper AppData –in example, Encrypted Files –in example, MAXScript System Globals, Node User-Defined Properties and Methods –in example

rectify Box2 Values

refine NURBSCVCurve : NURBSCurve, NURBSCVSurface : NURBSSurface, NURBSPointCurve : NURBSCurve, NURBSPointSurface : NURBSSurface

refineU NURBSCVSurface : NURBSSurface, NURBSPointSurface : NURBSSurface

refineV NURBSCVSurface : NURBSSurface, NURBSPointSurface : NURBSSurface

removeObject Modifying Existing NURBS Objects, NURBSSet : Value

renderMap Material Editor, TextureMap Common Properties, Operators, and Methods

reparameterize NURBSCVCurve : NURBSCurve, NURBSCVSurface : NURBSSurface

replace String Literals

resample

reset Curve Control, Flex interfaces:

resetZoom

save Bitmap Values

seek FileStream Values, StringStream Values, Controller Key Functions

setAppData Access to MAXWrapper AppData

setCacheEntry

setCurve NURBS1RailSweepSurface : NURBSSurface, NURBS2RailSweepSurface : NURBSSurface, NURBSULoftSurface : NURBSSurface

setCurveByID NURBS1RailSweepSurface : NURBSSurface, NURBS2RailSweepSurface : NURBSSurface, NURBSULoftSurface : NURBSSurface

setCurveStartPoint NURBS1RailSweepSurface : NURBSSurface, NURBS2RailSweepSurface : NURBSSurface

setCV NURBSCVCurve : NURBSCurve, NURBSCVSurface : NURBSSurface, Creating New NURBS Objects –in example

setDisplacementMapping Editable_Mesh : GeometryClass and TriMesh : Value

setEdge NURBSBlendSurface : NURBSSurface, NURBSNBlendSurface : NURBSSurface

setEdgeVis Editable_Mesh : GeometryClass and TriMesh : Value

setface Editable_Mesh : GeometryClass and TriMesh : Value, Working with Editable Meshes –in example

setFaceMatID Editable_Mesh : GeometryClass and TriMesh : Value

setfacenormal Editable_Mesh : GeometryClass and TriMesh : Value

setFaceSmoothGroup Editable_Mesh : GeometryClass and TriMesh : Value

setFade

setFlip NURBS1RailSweepSurface : NURBSSurface, NURBS2RailSweepSurface : NURBSSurface, NURBSULoftSurface : NURBSSurface, path interfaces:, Path_Constraint interfaces:

setFlipTrim NURBSFilletSurface : NURBSSurface

setGenerateUVs NURBSSurface : NURBSObject

setIndexedPixels Bitmap Files

setKnot NURBSCVCurve : NURBSCurve, Creating New NURBS Objects –in example

setMesh Editable_Mesh : GeometryClass and TriMesh : Value, Scripted SimpleObject Plug-ins –in example

SetNonUniformScale BipedExportInterface Values

setnormal Editable_Mesh : GeometryClass and TriMesh : Value

setNumCPVVerts Editable_Mesh : GeometryClass and TriMesh : Value

setNumFaces Editable_Mesh : GeometryClass and TriMesh : Value

setNumTVerts Editable_Mesh : GeometryClass and TriMesh : Value

setNumVerts Editable_Mesh : GeometryClass and TriMesh : Value, Patches

setObject NURBSSet : Value, Modifying Existing NURBS Objects

setParent NURBSBlendSurface : NURBSSurface, NURBSFilletSurface : NURBSSurface, NURBSMultiCurveTrimSurface : NURBSSurface, NURBSNBlendSurface : NURBSSurface

setParentID NURBSBlendSurface : NURBSSurface, NURBSFilletSurface : NURBSSurface, NURBSMultiCurveTrimSurface : NURBSSurface, NURBSNBlendSurface : NURBSSurface

setPixels Bitmap Files, Scripted RenderEffect Plug-ins –in example

setPoint Curve Control, NURBSPointCurve : NURBSCurve, NURBSPointSurface : NURBSSurface, NURBSTextureSurface : Value

setProdTess NURBSSet : Value, NURBSSurface : NURBSObject

setRadius NURBSFilletSurface : NURBSSurface

setSeed NURBSFilletSurface : NURBSSurface

setSize BigMatrix Values

setSplitMesh Editable_Mesh : GeometryClass and TriMesh : Value

setStruct

setSubdivisionDisplacement Editable_Mesh : GeometryClass and TriMesh : Value

setTextureSurface NURBSSurface : NURBSObject, NURBSTextureSurface : Value

setTextureUVs NURBSSurface : NURBSObject, Materials Assignment and Texture Coordinates

setTiling NURBSSurface : NURBSObject

setTilingOffset NURBSSurface : NURBSObject

setTrimSurface NURBSFilletSurface : NURBSSurface

settvert Editable_Mesh : GeometryClass and TriMesh : Value, Working with Editable Meshes

setTVFace Editable_Mesh : GeometryClass and TriMesh : Value, Working with Editable Meshes

setUCurve NURBSUVLoftSurface : NURBSSurface

setUCurveByID NURBSUVLoftSurface : NURBSSurface

setUKnot NURBSCVSurface : NURBSSurface

setVCFace Editable_Mesh : GeometryClass and TriMesh : Value

setVCurve NURBSUVLoftSurface : NURBSSurface

setVCurveByID NURBSUVLoftSurface : NURBSSurface

setVert Editable_Mesh : GeometryClass and TriMesh : Value, Patches

setVertColor Editable_Mesh : GeometryClass and TriMesh : Value

setViewTess NURBSSet : Value, NURBSSurface : NURBSObject

setVKnot NURBSCVSurface : NURBSSurface

showInterface Class and Object Inspector Functions, Trackviews

showInterfaces Class and Object Inspector Functions, List Controller

showProperties Apropos" and "ShowProperties" and now "Help" and "Show", Class and Object Inspector Functions

showTrack

skipToNextLine FileStream Values, StringStream Values

skipToString FileStream Values, StringStream Values

Slerp EulerAngles Values, Quat Values

sort Array Values

sortNoteKeys MAXNoteKeyArray Values, Working with Note Tracks - in example

squad Quat Values

substring String Literals

superClassOf Working with Values, Structure Inherited Methods, Value Common Properties, Operators, and Methods, Picking Scene Nodes By Hit

supportsTimeOperations Controller Time Functions

transform

transpose BigMatrix Values

unDisplay Bitmap Files

update

updateXRef XRefObject : Node, XRefScene Values

XFormMat Matrix3 Values

zoom

See also

Definitions for MAXScript internal organization


Const MappedGeneric

addEaseCurve Controller Ease and Multiplier Curve Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

addNewKey MAXKey Common Properties, Operators, and Methods

deleteEaseCurve Controller Ease and Multiplier Curve Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

deleteKeys MAXKeyArray Values, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies, Controller Key Functions

deleteTime Controller Time Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

deselectKeys Nested Object Controller Functions, Time and Key Functions on Object Hierarchies, Controller Key Functions

enableORTs Controller Out-Of-Range Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

Identity BigMatrix Values

insertTime Controller Time Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

mapKeys mapKeys() method

moveKeys MAXKeyArray Values, Controller Key Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

Orthogonalize Matrix3 Values

PreRotate Matrix3 Values

PreRotateX Matrix3 Values

PreRotateY Matrix3 Values

PreRotateZ Matrix3 Values

PreScale Matrix3 Values

PreTranslate Matrix3 Values

print Value Common Properties, Operators, and Methods

reduceKeys Controller Key Reducer, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

reverseTime Controller Time Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

RotateX Matrix3 Values

RotateY Matrix3 Values

RotateZ Matrix3 Values

scaleTime Controller Time Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

selectKeys Controller Key Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies, Attachment : PositionController

setAfterORT Controller Ease and Multiplier Curve Functions, Controller Out-Of-Range Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

setBeforeORT Names, Controller Ease and Multiplier Curve Functions, Controller Out-Of-Range Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

setTimeRange Controller Time Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies

sortKeys MAXKeyArray Values, Controller Key Functions, Nested Object Controller Functions, Time and Key Functions on Object Hierarchies, Working with MAXKey Values, Working with Note Tracks

Translate Matrix3 Values, Box2 Values

Zero

See also

Definitions for MAXScript internal organization


Const NodeGeneric

addAndWeld SplineShape : Shape

addKnot SplineShape : Shape

addModifier

addNewSpline SplineShape : Shape

addNURBSSet Modifying Existing NURBS Objects, NURBS Node Properties and Methods, Parameter Ranges for Curves and Surfaces

bindKnot SplineShape : Shape

bindSpaceWarp

breakCurve NURBS Node Properties and Methods

breakSurface Modifying Existing NURBS Objects, NURBS Node Properties and Methods

collapseStack Editable_Mesh : GeometryClass and TriMesh : Value, Modifier Common Properties, Operators, and Methods, Node Common Properties, Operators, and Methods, Patch : GeometryClass

convertTo Editable_Mesh : GeometryClass and TriMesh : Value, Node Common Properties, Operators, and Methods, NURBS Node Properties and Methods, Patch : GeometryClass, Patches

convertToMesh

convertToNURBSCurve Collections, Node Common Properties, Operators, and Methods, NURBS Node Properties and Methods

convertToNURBSSurface Node Common Properties, Operators, and Methods, NURBS Node Properties and Methods

convertToPoly

convertToSplineShape Modifier Common Properties, Operators, and Methods, Node Common Properties, Operators, and Methods, NURBS Node Properties and Methods, Scripting Vertex and Control Point Animation, Section : Shape, SplineShape : Shape

copy

curveLength Shape Common Properties, Operators, and Methods

deleteKnot SplineShape : Shape

deleteModifier Modifier Common Properties, Operators, and Methods, Node Common Properties, Operators, and Methods

deleteSpline SplineShape : Shape, Modifier and SpacewarpModifier Types

deselect

flagForeground Node Common Properties, Operators, and Methods, Scripted Atmospheric Plug-ins - in example, Slider, Spinner

freeze

getEdgeSelection Edit_Mesh : Modifier, Editable_Mesh : GeometryClass and TriMesh : Value, Mesh_Select : Modifier, polyop const StructDef

getFaceSelection Edit_Mesh : Modifier, Editable_Mesh : GeometryClass and TriMesh : Value, Mesh_Select : Modifier, polyop const StructDef

getInVec SplineShape : Shape

getKnotPoint SplineShape : Shape

getKnotType SplineShape : Shape

getNURBSSet

getOutVec SplineShape : Shape

getSegmentType SplineShape : Shape

getUserProp Node Common Properties, Operators, and Methods, Node User-Defined Properties and Methods

getUserPropBuffer Node Common Properties, Operators, and Methods, Node User-Defined Properties and Methods

getVertSelection Edit_Mesh : Modifier, Editable_Mesh : GeometryClass and TriMesh : Value, Mesh_Select : Modifier, polyop const StructDef

hide

hideSelectedSegments

hideSelectedSplines

hideSelectedVerts

instance

instanceReplace Node Common Properties, Operators, and Methods

intersectRay mouseTrack() Function, Node Common Properties, Operators, and Methods

intersects Node Common Properties, Operators, and Methods, Scripted Manipulator

isClosed NURBSCurve : NURBSObject, SplineShape : Shape

isDeleted Node Common Properties, Operators, and Methods - in example with def, PathName Values - in example with def

joinCurves NURBS Node Properties and Methods

joinSurfaces NURBS Node Properties and Methods

lengthInterp Shape Common Properties, Operators, and Methods

lengthTangent Shape Common Properties, Operators, and Methods

lengthToPathParam Shape Common Properties, Operators, and Methods

makeIndependent NURBS Node Properties and Methods

materialID Bitmap Values, MaterialModifier : Modifier, SplineShape : Shape

move

nearestPathParam Shape Common Properties, Operators, and Methods

numKnots NURBSCVCurve : NURBSCurve, Creating New NURBS Objects – in example, Shape Common Properties, Operators, and Methods, SplineShape : Shape

numSegments SplineShape : Shape

numSplines SplineShape : Shape

open

particleAge Particle System Common Properties, Operators, and Methods

particleCount Particle System Common Properties, Operators, and Methods

particlePos Particle System Common Properties, Operators, and Methods

particleSize Particle System Common Properties, Operators, and Methods

particleVelocity Particle System Common Properties, Operators, and Methods

pathInterp Particle System Common Properties, Operators, and Methods

pathTangent Particle System Common Properties, Operators, and Methods

pathToLengthParam Shape Common Properties, Operators, and Methods

printstack Node Common Properties, Operators, and Methods

reference

referenceReplace Node Common Properties, Operators, and Methods

refineSegment SplineShape : Shape

resetShape SplineShape : Shape

reverse

rotate

scale

select

selectmore Node Common Properties, Operators, and Methods, ObjectSet Values - In Example With Def

setEdgeSelection polyop const StructDef, Editable_Mesh : GeometryClass and TriMesh : Value - In Example

setFaceSelection polyop const StructDef, Editable_Mesh : GeometryClass and TriMesh : Value - In Example

setFirstKnot SplineShape : Shape

setFirstSpline SplineShape : Shape

setInVec SplineShape : Shape

setKnotPoint SplineShape : Shape

setKnotType SplineShape : Shape

setOutVec SplineShape : Shape

setRenderApproximation NURBS Node Properties and Methods, NURBSSurfaceApproximation : Value

setSegmentType SplineShape : Shape

setSurfaceDisplay NURBS Node Properties and Methods, NURBSSurfaceApproximation : Value

setUserProp Node Common Properties, Operators, and Methods, Node User-Defined Properties and Methods - In Example With Def

setUserPropBuffer Node Common Properties, Operators, and Methods, Node User-Defined Properties and Methods - In Example With Def

setVertSelection Editable_Mesh : GeometryClass and TriMesh : Value - In Example With Def, polyop const StructDef

setViewApproximation NURBS Node Properties and Methods, NURBSSurfaceApproximation : Value

snapShot Editable_Mesh : GeometryClass and TriMesh : Value, Node Common Properties, Operators, and Methods

unbindKnot SplineShape : Shape

unfreeze 3ds max Commands, 3ds max Commands in MAXScript, Node Common Properties, Operators, and Methods, Unwrap_UVW interfaces:, UVWUnwrap interfaces:, Visual MAXScript

unhide

unhideSegments SplineShape : Shape

updateBindList SplineShape : Shape

updateShape SplineShape : Shape

See also

Definitions for MAXScript internal organization


Const Primitives

All known const Primitives.

Acos Number Values

addAtmospheric Atmospheric Effects Common Properties, Operators, and Methods

addEffect Render Effects Common Properties, Operators, and Methods

addMorphTarget Barycentric_Morph_Controller : MorphController

addNoteTrack Notetrack Values, Working with Note Tracks

addRollout Utility Clauses, Managing Multiple Rollouts in a Scripted Utility, Rollout Floater Windows, Scripted Utilities, Utility and Rollout Properties, Methods, and Event Handlers

addTrackViewController Track View Nodes

affectRegionVal Affect Region Function

amax Array Values

amin Array Values

animateAll Scripting Vertex and Control Point Animation, Modifier Sub-Object Transform Properties

animateVertex SplineShape : Shape, Scripting Vertex and Control Point Animation

Modifier Sub-Object Transform Properties Scripting_Vertex_and_Control_Point_Animation

appendSubSelSet Main Toolbar

apropos Class and Object Inspector Functions, Apropos" and "ShowProperties" and now "Help" and "Show"

arbAxis Point3 Values

asin Number Values

assignNewName Material Common Properties, Operators, and Methods

atan Number Values

atan2 Number Values

attachObjects Node Common Properties, Operators, and Methods

averageSelVertCenter Editable_Mesh : GeometryClass and TriMesh : Value

averageSelVertNormal Editable_Mesh : GeometryClass and TriMesh : Value

axisTripodLocked Miscellaneous Viewport Methods and System Globals

boxPickNode Picking Scene Nodes By Region

break

ceil Number Values

checkForSave 3ds max File Loading and Saving

circlePickNode Picking Scene Nodes By Region

clearCurSelSet Main Toolbar

clearListener Controlling the Listener Contents and the Insertion Point

clearNodeSelection Node Common Properties, Operators, and Methods

clearSelection ObjectSet Values, Node Common Properties, Operators, and Methods, Trackviews

ClearSubSelSets Main Toolbar

clearUndoBuffer undo, Exiting and Resetting 3ds max

closelog Turning On the Listener Log

closeRolloutFloater Rollout Floater Windows

closeUtility Utility and Rollout Properties, Methods, and Event Handlers

completeRedraw Refreshing the Viewports

configureBitmapPaths Miscellaneous Dialogs

conformToShape FFD_2x2x2 : Modifier, FFD_3x3x3 : Modifier, FFD_4x4x4 : Modifier, FFD_Box : Modifier, FFD_Cyl : Modifier

copyFile External File Methods

cos Trigonometric Functions, Function Variables, Number Values

cosh Mathematical Operations in MAXScript, Number Values

CreateDialog CreateDialog

createfile FileStream Values, Encrypted Files

createLockKey Controller Key Functions

createMorphObject Barycentric_Morph_Controller : MorphController, Barycentric_Morph_Controller Keys, Morph : GeometryClass

createOLEObject OLE Automation

createPreview Miscellaneous Viewport Methods and System Globals

createReaction Reactor Controllers

degToRad Number Values

deleteAllChangeHandlers Change Handlers and When Constructs

deleteAtmospheric Atmospheric Effects Common Properties, Operators, and Methods

deleteChangeHandler Change Handlers and When Constructs

deleteEffect Render Effects Common Properties, Operators, and Methods

deleteFile External File Methods

deleteMorphTarget Barycentric_Morph_Controller : MorphController

deleteNoteTrack Notetrack Values, Working with Note Tracks

deleteReaction Reactor Controllers

deleteTrackViewController Track View Nodes

deleteTrackViewNode Track View Nodes

dependsOn dependsOn For Scripted Controllers

deselectHiddenEdges Editable_Mesh : GeometryClass and TriMesh : Value

deselectHiddenFaces Editable_Mesh : GeometryClass and TriMesh : Value

deselectNode Node Common Properties, Operators, and Methods

DestroyDialog CreateDialog

DisableSceneRedraw Refreshing the Viewports

disableStatusXYZ Coordinate Display

displayControlDialog Controller Common Properties, Operators, and Methods

displayTempPrompt Prompt Line

doesFileExist File Name Parsing

DOSCommand Executing External Commands

dumpMAXStrings

editAtmosphere Atmospheric Effects Common Properties, Operators, and Methods

editAtmospheric Atmospheric Effects Common Properties, Operators, and Methods

editEffect Render Effects Common Properties, Operators, and Methods

enableCoordCenter Main Toolbar

enableRefCoordSys Main Toolbar

EnableSceneRedraw Refreshing the Viewports

enableShowEndRes Modify Panel

enableStatusXYZ Coordinate Display

enableSubObjSel Modify Panel

enableUndo Main Toolbar

encryptFile Encrypted Files

encryptScript Encrypting Script Files

enumerateFiles Bitmap Files, BitmapTexture : TextureMap

eulerToQuat Quat Values, EulerAngles Values

exclusionListDlg Miscellaneous Dialogs

explodeGroup Node Common Properties, Operators, and Methods

exportFile 3ds max File Loading and Saving

fclose BinStream for Binary Reading and Writing

fencePickNode Picking Scene Nodes By Region

fetchMaxFile 3ds max File Loading and Saving

filein Zip-file Script Packages, Running Scripts, Including Scripts Within Scripts, Creating Functions, Encrypting Script Files, Symbolic Pathnames

filenameFromPath File Name Parsing

fileOpenMatLib Material Editor, MaterialLibrary Values

fileSaveAsMatLib Material Editor, MaterialLibrary Values

fileSaveMatLib Material Editor, MaterialLibrary Values

filterString String Values

flashNodes Miscellaneous Viewport Methods and System Globals

floor Number Literals

flushlog Turning On the Listener Log

fopen BinStream for Binary Reading and Writing

ForceCompleteRedraw Refreshing the Viewports

format StringStream Values

fractalNoise Color Values, Point3 Values

freeSceneBitmaps Bitmap Values, BitmapTexture : TextureMap, Miscellaneous Functions

freezeSelection Status Bar Buttons

fseek BinStream for Binary Reading and Writing

ftell BinStream for Binary Reading and Writing

gc Manual Garbage Collection, Bitmap Values

genClassID Scripted Plug-ins, Scripted Custom Attributes

getActiveCamera Accessing Active Viewport Info, Type, and Transforms, Defining Macro Scripts, Viewport Drawing Methods

getAtmospheric Atmospheric Effects Common Properties, Operators, and Methods, Setting explosion start and end times for Fire_Effect

getBackGround SetBackground Method

getBackGroundController Working with Atmospherics

getBipedExportInterface BipedExportInterface Values

getBitmapOpenFileName Bitmap Values

getBitmapSaveFileName Bitmap Values

getBkgFrameNum Viewport Background Images

getBkgImageAnimate Viewport Background Images

getBkgImageAspect Viewport Background Images

getBkgORType Viewport Background Images

getBkgRangeVal Viewport Background Images

getBkgStartTime Viewport Background Images

getBkgSyncFrame Viewport Background Images

getCommandPanelTaskMode Command Panels

getCoordCenter Main Toolbar, Node Common Properties, Operators, and Methods -in example

getCoreInterfaces Interfaces

getCPTM Accessing Active Viewport Info, Type, and Transforms

getCrossing Status Bar Buttons

getCurNameSelSet

getCurrentSelection Collections, ObjectSet Values

getCVertMode Node Common Properties, Operators, and Methods

GetDefaultUIColor 3ds max User Interface Colors

getDimensions FFD_Box : Modifier, FFD_Cyl : Modifier

GetDir 3ds max System Directories, SetDir

getDirectories External File Methods

GetDisplayFilter Selection Filter

getEffect Render Effects Common Properties, Operators, and Methods

getEulerMatAngleRatio EulerAngles Values, Matrix3 Values

getEulerQuatAngleRatio Quat Values, EulerAngles Values

getFileAttribute External File Methods

getFileCreateDate External File Methods

getFileModDate External File Methods

getFilenameFile Viewport Drawing Methods, File Name Parsing, External File Methods, Defining Macro Scripts

getFilenamePath File Name Parsing

getFilenameType External File Methods, File Name Parsing

getFiles External File Methods

getFileVersion External File Methods External_File_Methods

getGridMajorLines Viewport Grids

getGridSpacing Viewport Grids

getHashValue Value Common Properties, Operators, and Methods

getImageBlurMultController Node Common Properties, Operators, and Methods, General Node Properties

getInheritanceFlags Node Common Properties, Operators, and Methods

getInheritVisibility Node Common Properties, Operators, and Methods

getINISetting Accessing INI File Keys

getKBChar Keyboard Entry

getKBLine Keyboard Entry

getKBPoint Keyboard Entry

getKBValue Keyboard Entry

getKeyStepsPos Time Configuration Dialog

getKeyStepsRot Time Configuration Dialog

getKeyStepsScale Time Configuration Dialog Time_Configuration_Dialog Time_Configuration_Dialog

getKeyStepsSelOnly Time Configuration Dialog

getKeyStepsUseTrans Time Configuration Dialog

getKnotSelection SplineShape : Shape

getListenerSel Controlling the Listener Contents and the Insertion Point

getListenerSelText Controlling the Listener Contents and the Insertion Point

getMaterialID SplineShape : Shape

getMatLibFileName Material Editor, MaterialLibrary Values

getMAXFileObjectNames 3ds max File Loading and Saving, Zip-file Script Packages

getMAXOpenFileName 3ds max Open & Save Dialogs

getMAXSaveFileName 3ds max Open & Save Dialogs

getMeditMaterial Material Common Properties, Operators, and Methods, Material Editor, MaterialLibrary Values

getMKKey Barycentric_Morph_Controller : MorphController, Barycentric_Morph_Controller Keys

getMKKeyIndex Barycentric_Morph_Controller : MorphController

getMKTargetNames Barycentric_Morph_Controller : MorphController

getMKTargetWeights Barycentric_Morph_Controller : MorphController

getMKTime Barycentric_Morph_Controller Keys

getMKWeight Barycentric_Morph_Controller Keys

getMTLMEditFlags Material Common Properties, Operators, and Methods

getMTLMeditObjType Material Common Properties, Operators, and Methods

getMTLMeditTiling Material Common Properties, Operators, and Methods

getNamedSelSetItem SelectionSetArray Values

getNamedSelSetItemCount SelectionSetArray Values

getNamedSelSetName SelectionSetArray Values

getNodeByName Node Common Properties, Operators, and Methods

getNoteTrack Notetrack Values, MAXNoteKeyArray Values, Working with Note Tracks

getNumAxis Main Toolbar

getNumberDisplayFilters Selection Filter

getNumberSelectFilters Selection Filter

getNumNamedSelSets SelectionSetArray Values

getOpenFileName Standard Open and Save File Dialogs, ActiveX Controls in MAXScript Rollouts -in example

getPatchSteps Patch : GeometryClass

getPhyContextExport Biped and Physique, PhyContextExport Values

getPointController Controller Common Properties, Operators, and Methods

getPointControllers Controller Common Properties, Operators, and Methods

getPolygonCount Node Common Properties, Operators, and Methods

getPosTaskWeight Node Common Properties, Operators, and Methods

getProgressCancel Progress Bar Display

getProperty Class and Object Inspector Functions, Curve Control-in example, ActiveX Controls in MAXScript Rollouts -in example

getPropertyController Class and Object Inspector Functions

getReactionCount Reactor Controllers

getReactionFalloff Reactor Controllers

getReactionInfluence Reactor Controllers

getReactionName Reactor Controllers

getReactionState Reactor controller - in example, Reactor Controllers

getReactionStrength Reactor Controllers

getReactionValue Reactor controller - in example, Reactor Controllers

getRefCoordSys Main Toolbar

getRendApertureWidth Render Scene Dialog

getRenderID Node Common Properties, Operators, and Methods

getRendImageAspect Render Scene Dialog

getRotTaskWeight Node Common Properties, Operators, and Methods

getSaveFileName Standard Open and Save File Dialogs, Viewport Drawing Methods- in example, Defining Macro Scripts - in example

getSavePath Standard Open and Save File Dialogs

getSaveRequired Exiting and Resetting 3ds max, undo

getScreenScaleFactor Accessing Active Viewport Info, Type, and Transforms

getSegLengths SplineShape : Shape

getSegSelection SplineShape : Shape

getSelectedReactionNum Reactor Controllers

GetSelectFilter Selection Filter

getShadeCVerts Node Common Properties, Operators, and Methods

getSnapMode Status Bar Buttons

getSnapState Status Bar Buttons

getSplineSelection SplineShape : Shape

getTaskAxisState Node Common Properties, Operators, and Methods

getTextExtent getTextExtent getTextExtent

GetTMController

gettoolbtnstate Main Toolbar

getTrajectoryOn Node Common Properties, Operators, and Methods

getTransformAxis Node Common Properties, Operators, and Methods

getTransformLockFlags Node Common Properties, Operators, and Methods

GetUIColor 3ds max User Interface Colors

getUseDraftRenderer Render Scene Dialog

getUseEnvironmentMap Working with Atmospherics

getViewFOV Accessing Active Viewport Info, Type, and Transforms

getViewSize Accessing Active Viewport Info, Type, and Transforms, ActiveX Controls in MAXScript Rollouts - in example

getViewTM Accessing Active Viewport Info, Type, and Transforms

getVisController General Node Properties, Node Common Properties, Operators, and Methods

getVPortBGColor Miscellaneous Viewport Methods and System Globals

getXYZControllers XYZ Controllers

group Node Common Properties, Operators, and Methods

hasNoteTracks Notetrack Values, Working with Note Tracks -in example

hasProperty hasProperty() function

HitByNameDlg Main Toolbar

holdMaxFile 3ds max File Loading and Saving

importFile Zip-file Script Packages, 3ds max File Loading and Saving

include Including Scripts Within Scripts, Symbolic Pathnames

insertItem Array Values

interpCurve3D SplineShape : Shape

intersectRayEx Node Common Properties, Operators, and Methods

invalidateTM Node Common Properties, Operators, and Methods

invalidateTreeTM Node Common Properties, Operators, and Methods

invalidateWS Node Common Properties, Operators, and Methods

isActive

isBoneOnly Node Common Properties, Operators, and Methods

isController Value Common Properties, Operators, and Methods

isCPEdgeOnInView Miscellaneous Viewport Methods and System Globals

isCreatingObject

isGroupHead Node Common Properties, Operators, and Methods

isGroupMember Node Common Properties, Operators, and Methods

IsNetServer Miscellaneous Functions

isOpenGroupHead Node Common Properties, Operators, and Methods

isOpenGroupMember Node Common Properties, Operators, and Methods

IsPointSelected Node Common Properties, Operators, and Methods, NURBS Node Properties and Methods

isreadOnly

isSceneRedrawDisabled Refreshing the Viewports

isSelectionFrozen Status Bar Buttons

IsShapeObject Node Common Properties, Operators, and Methods

isStruct Value Common Properties, Operators, and Methods

isStructDef Value Common Properties, Operators, and Methods

IsSubSelEnabled Modify Panel Modify_Panel

isSurfaceUVClosed Node Common Properties, Operators, and Methods

isValidNode isValidNode

LoadDefaultMatLib Material Editor, MaterialLibrary Values

loadDllsFromDir Miscellaneous Functions

loadMaterialLibrary Material Editor, MaterialLibrary Values, Zip-file Script Packages

loadMaxFile 3ds max File Loading and Saving, Zip-file Script Packages, Running Scripts from the Command Line-in example, Mouse Cursors-in example, External File Methods -in example

locals Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code, What's New in MAXScript, Viewport Redraw Callback Mechanism, Time Change Callback Mechanism, String Values, Scripted Plug-in Clauses, Scripted Custom Attributes, Script Controllers, Scope of Variables

lockAxisTripods Miscellaneous Viewport Methods and System Globals

log Number Values

log10 Number Values

makeDir External File Methods

MakeNURBSConeSurface Creating NURBSCVSurface Values

MakeNURBSCylinderSurface Creating NURBSCVSurface Values

MakeNURBSLatheSurface Creating NURBSCVSurface Values

MakeNURBSSphereSurface Creating NURBSCVSurface Values

MakeNURBSTorusSurface Creating NURBSCVSurface Values

mapScreenToCP Accessing Active Viewport Info, Type, and Transforms

mapScreenToView Accessing Active Viewport Info, Type, and Transforms

mapScreenToWorldRay Accessing Active Viewport Info, Type, and Transforms

matchPattern String Values, ActiveX Controls in MAXScript Rollouts -in example

MaterialBrowseDlg Miscellaneous Dialogs

MatrixFromNormal Matrix3 Values, Point3 Values

maxVersion Miscellaneous Functions

mergeMaxFile Node Common Properties, Operators, and Methods, 3ds max File Loading and Saving, Zip-file Script Packages

messageBox MAXScript Message and Query Dialogs

mirrorIKConstraints Node Common Properties, Operators, and Methods

mod 3ds max Commands

mouseTrack mouseTrack() Function

namedSelSetListChanged Main Toolbar

newRolloutFloater Rollout Floater Windows,Scripted_Utilities Scripted Utilities, Curve Control -in example

newScript WindowStream Values, The MAXScript Editor Windows

newTrackViewNode Track View Nodes

nodeColorPicker Miscellaneous Dialogs

nodeIKParamsChanged Node Common Properties, Operators, and Methods

nodeInvalRect Refreshing the Viewports, Node Common Properties, Operators, and Methods -in example

noise3 Color Values, Point3 Values

noise4 Color Values, Point3 Values Color_Values

normtime Time Values

numMapsUsed Editable_Mesh : GeometryClass and TriMesh : Value

numNoteTracks Notetrack Values, Working with Note Tracks -in example

numSurfaces Node Common Properties, Operators, and Methods

NURBSExtrudeNode Creating NURBS Scene Objects

NURBSLatheNode Creating NURBS Scene Objects

NURBSNode Using the NURBS Classes and Functions to Create and Modify 3ds max NURBS Models

OkMtlForScene Interface: medit

OKToBindToNode Node Common Properties, Operators, and Methods

openBitMap Bitmap Values

openCTBitMap

openEncryptedFile FileStream Values, Encrypted Files

openfile Function Parameters -in example, FileStream Values

openlog Turning On the Listener Log

openUtility Utility and Rollout Properties, Methods, and Event Handlers

pickObject startObjectCreation(), RubberBanding in pickObject() Function, Picking Scene Nodes By Hit

pickOffsetDistance Picking Points in the Viewports

pickPoint Keyboard Entry, Picking Points in the Viewports

playAnimation Time Control

pointSelection NURBS Node Properties and Methods, Node Common Properties, Operators, and Methods

popPrompt Prompt Line

popupMenu

pow Number Values

progressEnd Progress Bar Display

progressStart Progress Bar Display

progressUpdate Progress Bar Display

PushPrompt Prompt Line

qsort Array Values

quatToEuler EulerAngles Values, Quat Values

queryBox MAXScript Message and Query Dialogs

quitMax Running Scripts from the Command Line, Exiting and Resetting 3ds max

radToDeg Number Values

reactTo Reactor controller, Reactor Controllers

ReadByte BinStream for Binary Reading and Writing

ReadFloat BinStream for Binary Reading and Writing

ReadLong BinStream for Binary Reading and Writing

ReadShort BinStream for Binary Reading and Writing

ReadString BinStream for Binary Reading and Writing

redrawViews Refreshing the Viewports, Picking Points in the Viewports, Node Common Properties, Operators, and Methods -in example, Change Handlers and When Constructs

registerDisplayFilterCallback

registerOLEInterface Exposing MAXScript Functions, Running the OLE Demo

registerRedrawViewsCallback Viewport Redraw Callback Mechanism

registerRightClickMenu Scripted Right-Click Menus, subMenu -in example, separator -in example, menuItem -in example

registerSelectFilterCallback class id filter

registerTimeCallback Time Change Callback Mechanism

registerViewWindow Rollout Floaters as Extended viewports, ActiveX Controls in MAXScript Rollouts

releaseAllOLEObjects OLE Automation

releaseOLEObject OLE Automation

removeRollout Utility and Rollout Properties, Methods, and Event Handlers, Rollout Floater Windows, Managing Multiple Rollouts in a Scripted Utility, Utility Clauses -in example, Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code

removeTempPrompt Prompt Line

renameFile External File Methods

render Controlling the Renderer, General Event Callback Mechanism

replaceInstances MAXWrapper Common Properties, Operators, and Methods

replacePrompt Prompt Line

rescaleWorldUnits Miscellaneous Functions

resetLattice FFD_2x2x2 : Modifier, FFD_3x3x3 : Modifier, FFD_4x4x4 : Modifier, FFD_Box : Modifier, FFD_Cyl : Modifier

resetLengthInterp Shape Common Properties, Operators, and Methods

resetMaxFile Exiting and Resetting 3ds max

rotateXMatrix Matrix3 Values

rotateYMatrix Matrix3 Values

rotateYPRMatrix Matrix3 Values

rotateZMatrix Matrix3 Values

saveMaterialLibrary Material Editor, MaterialLibrary Values

saveMaxFile 3ds max File Loading and Saving

saveNodes 3ds max File Loading and Saving, SelectionSetArray Values

scaleMatrix Matrix3 Values

seed Number Values

selectBitMap Bitmap Values

selectByName Picking Scene Nodes by Name

selectCTBitMap

selectReaction Reactor Controllers

selectSaveBitMap Bitmap Values

setActive Atmospheric Effects Common Properties, Operators, and Methods, Render Effects Common Properties, Operators, and Methods

setArrowCursor Mouse Cursors

setAtmospheric Atmospheric Effects Common Properties, Operators, and Methods

setBackGround Working with Atmospherics, SetBackground Method

setBackGroundController Working with Atmospherics

setBkgFrameRange Viewport Background Images

setBkgImageAnimate Viewport Background Images

setBkgImageAspect Viewport Background Images

setBkgORType Viewport Background Images

setBkgStartTime Viewport Background Images

setBkgSyncFrame Viewport Background Images

SetCommandPanelTaskMode Command Panels

setCoordCenter Main Toolbar

setCurNamedSelSet Main Toolbar

setCVertMode Node Common Properties, Operators, and Methods

setDimensions FFD_Box : Modifier, FFD_Cyl : Modifier

SetDir SetDir

SetDisplayFilter Selection Filter

setEffect Render Effects Common Properties, Operators, and Methods

setFileAttribute External File Methods

setFocus

setGroupHead Node Common Properties, Operators, and Methods

setGroupMember Node Common Properties, Operators, and Methods

setGroupOpen Node Common Properties, Operators, and Methods

setImageBlurMultController Node Common Properties, Operators, and Methods, General Node Properties

setImageBlurMultiplier Node Common Properties, Operators, and Methods

setInheritanceFlags Node Common Properties, Operators, and Methods

setInheritVisibility Node Common Properties, Operators, and Methods

setINISetting Accessing INI File Keys

setKeyStepsPos Time Configuration Dialog

setKeyStepsRot Time Configuration Dialog

setKeyStepsScale Time Configuration Dialog

setKeyStepsSelOnly Time Configuration Dialog

setKeyStepsUseTrans Time Configuration Dialog

setKnotSelection SplineShape : Shape

setListenerSel Controlling the Listener Contents and the Insertion Point

setListenerSelText Controlling the Listener Contents and the Insertion Point

setMaterialID SplineShape : Shape

setMeditMaterial Material Common Properties, Operators, and Methods, Material Editor, MaterialLibrary Values

setMKTime Barycentric_Morph_Controller Keys

setMKWeight Barycentric_Morph_Controller Keys

setMorphTarget Barycentric_Morph_Controller : MorphController

setMorphTargetName Barycentric_Morph_Controller : MorphController

setMotBlur Node Common Properties, Operators, and Methods

setMTLMEditFlags Material Common Properties, Operators, and Methods

setMTLMeditObjType Material Common Properties, Operators, and Methods

setMTLMeditTiling Material Common Properties, Operators, and Methods

setOpenSceneScript

setPatchSteps Patch : GeometryClass

setPosTaskWeight Node Common Properties, Operators, and Methods

setProgressCancel Progress Bar Display

setProperty Class and Object Inspector Functions, ActiveX Controls in MAXScript Rollouts -in example

SetPropertyController Class and Object Inspector Functions

setReactionFalloff Reactor Controllers

setReactionInfluence Reactor Controllers

setReactionName Reactor Controllers

setReactionState Reactor Controllers

setReactionStrength Reactor Controllers

setReactionValue Reactor Controllers

setRefCoordSys Main Toolbar

setRenderable Node Common Properties, Operators, and Methods

setRenderID Node Common Properties, Operators, and Methods

setRotTaskWeight Node Common Properties, Operators, and Methods

setSaveRequired Exiting and Resetting 3ds max, undo

setSaveSceneScript

setSegSelection SplineShape : Shape

SetSelectFilter Selection Filter

setShadeCVerts Node Common Properties, Operators, and Methods

setSilentMode Bitmap Values

setSplineSelection SplineShape : Shape

setStatusXYZ Coordinate Display

setSysCur Mouse Cursors

setTaskAxisState Node Common Properties, Operators, and Methods

setToolBtnState Main Toolbar

setTrajectoryOn Node Common Properties, Operators, and Methods

setTransformLockFlags Node Common Properties, Operators, and Methods

SetUIColor 3ds max User Interface Colors

setupEvents

SetUseDraftRenderer Render Scene Dialog

setUseEnvironmentMap Working with Atmospherics

setVPortBGColor Miscellaneous Viewport Methods and System Globals

setWaitCursor Mouse Cursors

ShellLaunch Executing External Commands

showAllActiveXControls ActiveX Controls in MAXScript Rollouts

showClass Class and Object Inspector Functions, Dynamic Properties

showEvents ActiveX Controls in MAXScript Rollouts

showMethods ActiveX Controls in MAXScript Rollouts ActiveX_Controls_in_MAXScript_Rollouts

showSource The MAXScript Editor Windows, Creating Functions

showTextureMap showTextureMap() function, Material Editor, Node Common Properties, Operators, and Methods -in example, TextureMap Common Properties, Operators, and Methods, Working with Editable Meshes

silentMode Bitmap Values

sin Number Values

sinh Number Values

sleep Pausing Script Execution

snapshotAsMesh Node Common Properties, Operators, and Methods

sqrt Number Values

squadrev Quat Values

startObjectCreation Create Panel, Defining Macro Scripts, startObjectCreation()

startTool Mouse Tool Clauses, Scripted Mouse Tools

stopAnimation Time Control

stopCreating Node Common Properties, Operators, and Methods, NURBS Node Properties and Methods, Modifying Existing NURBS Objects

stopTool Scripted Mouse Tools

subdivideSegment SplineShape : Shape

swap Miscellaneous Functions

tan Number Values

tangentCurve3D SplineShape : Shape

tanh Number Values

thawSelection Status Bar Buttons

timeStamp Time Stamping

TransMatrix Matrix3 Values, Scripted Manipulator -in example, Scripted Manipulators - in example

turbulence Color Values, Point3 Values

ungroup Node Common Properties, Operators, and Methods

uniqueName Node Common Properties, Operators, and Methods

unregisterAllRightClickMenus Scripted Right-Click Menus

unregisterRedrawViewsCallback Viewport Redraw Callback Mechanism

unregisterRightClickMenu Scripted Right-Click Menus

unregisterSelectFilterCallback class id filter

unregisterTimeCallback Time Change Callback Mechanism

unRegisterViewWindow Rollout Floaters as Extended viewports

updateMTLInMedit Material Common Properties, Operators, and Methods

updateSurfaceMapper Surface_Mapper : SpacewarpModifier

validModifier Node Common Properties, Operators, and Methods, validModifer() function, Modifier Common Properties, Operators, and Methods

WriteByte BinStream for Binary Reading and Writing

WriteFloat BinStream for Binary Reading and Writing

WriteLong BinStream for Binary Reading and Writing

WriteShort BinStream for Binary Reading and Writing

WriteString BinStream for Binary Reading and Writing

yesNoCancelBox MAXScript Message and Query Dialogs

See also

Definitions for MAXScript internal organization


Const StructDef

AttachCtrl

autoBackup

bit

boolObj

callbacks

cui

custAttributes

DOF

fileProperties

flexOps

gw

ik

keyboard

LE

LinkCtrl

ListCtrl

logsystem

macros

mapPaths

meshop

meshOps

modPanel

mouse

mtlBrowser

options

patch

patchOps

persistents

polyop

polyOps

patch.getEdgeVec21

preferences

refs

scanlineRender

schematicView

skinOps

snapMode

splineOps

sysInfo

systemTools

terrainOps

timeConfiguration

toolMode

trackbar

trackview

units

viewport

WAVsound

xrefPaths

xrefs

See also

Definitions for MAXScript internal organization


AttachCtrl const StructDef

Attachment : PositionController

AttachCtrl.addNewKey

AttachCtrl.getKey

Attachment Controller Keys


autoBackup const StructDef

3ds max System Globals

autoBackup.enabled SystemGlobal:enabled false

autoBackup.time SystemGlobal:time 5.0


bit const StructDef

Number Values

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

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

callbacks.addScript

callbacks.broadcastCallback

callbacks.removeScripts

callbacks.show


cui const StructDef

3ds max System Globals

Menu and CUI Loading

Command Panels

Custom User Interface Files

cui.commandPanelOpen SystemGlobal:commandPanelOpen true

cui.expertModeOff

cui.expertModeOn

cui.getConfigFile

cui.GetDir

cui.getExpertMode

cui.loadConfig

cui.saveConfig

cui.saveConfigAs

cui.setConfigFile


custAttributes const StructDef

Scripted Custom Attributes

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

DOF.addCam

DOF.addFocalNode

DOF.deleteCam

DOF.deleteCamByName

DOF.deleteFocalNode

DOF.deleteFocalNodeByName


fileProperties const StructDef

3ds max Scene File Properties

fileProperties.addProperty

fileProperties.deleteProperty

fileProperties.findProperty

fileProperties.getItems

fileProperties.getNumProperties

fileProperties.getPropertyName

fileProperties.getPropertyValue


flexOps const StructDef

Flex : Modifier

flexOps.ClearEdgeVertices

flexOps.GetNumberVertices

flexOps.GetVertexWeight

flexOps.isEdgeVertex

flexOps.SelectVertices

flexOps.SetEdgeVertices

flexOps.SetVertexWeights

See also

PositionSpring interfaces:

Point3Spring interfaces:

SpringPoint3Controller interfaces:

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController interfaces:

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex interfaces:

flexOps const StructDef


gw const StructDef

Viewport Drawing Methods

gw.clearScreen

gw.enlargeUpdateRect

gw.GetCPDisp

gw.getDriverString

gw.getFlipped

gw.GetFocalDist

gw.getHitherCoord

gw.getMaxLights

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


ik const StructDef

IK_ControllerMatrix3Controller : Matrix3Controller

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

3ds max System Globals

Keyboard Entry

keyboard.altPressed SystemGlobal:altPressed false

keyboard.controlPressed SystemGlobal:controlPressed false

keyboard.escPressed SystemGlobal:escPressed false

keyboard.shiftPressed SystemGlobal:shiftPressed false


LE const StructDef

Lens_Effects : RenderEffect

LE.addASec

LE.addGlow

LE.addLight

LE.addLightNode

LE.addMSec

LE.addRay

LE.addRing

LE.addStar

LE.addStreak

LE.deleteElement

LE.deleteElementByName

LE.deleteLight

LE.deleteLightByName

LE.lightIndex

LE.lightName

LE.load

LE.numLights

LE.save


LinkCtrl const StructDef

Link_Control : Matrix3Controller

LinkCtrl.addLink

LinkCtrl.deleteLink

LinkCtrl.getLinkCount

LinkCtrl.getLinkNode

LinkCtrl.getLinkTime

LinkCtrl.setLinkNode

LinkCtrl.setLinkTime


ListCtrl const StructDef

List Controller

ListCtrl.getActive

ListCtrl.getName

ListCtrl.setActive

ListCtrl.setName

See also

List Controllers


logsystem const StructDef

3ds max System Globals

logsystem.quietMode SystemGlobal:quietMode false


macros const StructDef

Macro Scripts

Defining Macro Scripts

macros.edit

macros.load

macros.new

macros.run


mapPaths const StructDef

3ds max System Directories

mapPaths.add

mapPaths.count

mapPaths.delete

mapPaths.get


meshop const StructDef

Editable_Mesh : GeometryClass and TriMesh : Value

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

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

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

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

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

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

modPanel.addModToSelection

modPanel.getCurrentObject

modPanel.getModifierIndex

modPanel.setCurrentObject

See also

Modifier Common Properties, Operators, and Methods

Modifier : MAXWrapper and SpacewarpModifier : MAXWrapper


mouse const StructDef

Mouse Cursors

mouse.buttonStates SystemGlobal:buttonStates #{}

mouse.mode SystemGlobal:mode 0

mouse.pos SystemGlobal:pos [106,85]

mouse.screenpos SystemGlobal:screenpos [657,577]


mtlBrowser const StructDef

Miscellaneous Dialogs

mtlBrowser.browseFrom

See also

mtlBrowser


options const StructDef

MAXScript System Globals

options.oldPrintStyles SystemGlobal:oldPrintStyles false

See also

Value Common Properties, Operators, and Methods


patch const StructDef

Patches

Patch : GeometryClass

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

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

patchOps const StructDef


patchOps const StructDef

Patch : GeometryClass

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

patch const StructDef

patchOps const StructDef

Patch_Select - superclass: modifier


persistents const StructDef

Persistent Global Variables

persistents.remove

persistents.removeAll

persistents.show


polyop const StructDef

Editable_Poly: GeometryClass

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

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

Editable_Poly: GeometryClass

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


preferences const StructDef

3ds max Globals

preferences.constantReferenceSystem SystemGlobal:constantReferenceSystem false

preferences.flyOffTime SystemGlobal:flyOffTime 300

preferences.maximumGBufferLayers SystemGlobal:maximumGBufferLayers 10

preferences.spinnerWrap SystemGlobal:spinnerWrap false

preferences.useLargeVertexDots SystemGlobal:useLargeVertexDots false

preferences.useTransformGizmos SystemGlobal:useTransformGizmos true

preferences.useVertexDots SystemGlobal:useVertexDots true

See also

Miscellaneous Viewport Methods and System Globals


refs const StructDef

MAXWrapper Common Properties, Operators, and Methods

refs.dependents


scanlineRender const StructDef

Render Scene Dialog

scanlineRender.antiAliasFilter SystemGlobal:antiAliasFilter Area:

scanlineRender.antiAliasFilterSize SystemGlobal:antiAliasFilterSize 1.5

scanlineRender.enablePixelSampler SystemGlobal:enablePixelSampler true

See also

3ds max Globals

3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters


schematicView const StructDef

Schematic View

schematicView.close

schematicView.getSchematicViewName

schematicView.numSchematicViews

schematicView.open

schematicView.zoomSelected


skinOps const StructDef

Skin : Modifier

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

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

snapMode.active SystemGlobal:active false

snapMode.type SystemGlobal:type 3D

See also

snapMode

3ds max System Globals


splineOps const StructDef

SplineShape : Shape

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

sysInfo.computername SystemGlobal:computername P3

sysInfo.cpucount SystemGlobal:cpucount 2

sysInfo.currentdir SystemGlobal:currentdir F:\M042

sysInfo.DesktopBPP SystemGlobal:DesktopBPP 16

sysInfo.DesktopSize SystemGlobal:DesktopSize [1280,1024]

sysInfo.getMAXMemoryInfo

sysInfo.getSystemMemoryInfo

sysInfo.MAXPriority SystemGlobal:MAXPriority normal

sysInfo.systemdir SystemGlobal:systemdir D:\WINNT\System32

sysInfo.tempdir SystemGlobal:tempdir D:\TEMP\

sysInfo.username SystemGlobal:username Administrator

sysInfo.windowsdir SystemGlobal:windowsdir D:\WINNT


systemTools const StructDef

System Tools

systemTools.GetScreenHeight

systemTools.GetScreenWidth

systemTools.IsDebugging

systemTools.IsWindows98or2000

systemTools.IsWindows9x

systemTools.NumberOfProcessors


terrainOps const StructDef

Terrain : GeometryClass

terrainOps.addOperand

terrainOps.deleteOperand

terrainOps.getOperand

terrainOps.getOperandTM

terrainOps.setOperandTM

terrainOps.update


timeConfiguration const StructDef

Time Configuration Dialog

timeConfiguration.playActiveOnly SystemGlobal:playActiveOnly true

timeConfiguration.playbackSpeed SystemGlobal:playbackSpeed 3

timeConfiguration.realTimePlayback SystemGlobal:realTimePlayback true

timeConfiguration.useTrackBar SystemGlobal:useTrackBar true

See also

3ds max System Globals


toolMode const StructDef

Main Toolbar

toolMode.AxisConstraints SystemGlobal:AxisConstraints XY

toolMode.CommandMode SystemGlobal:CommandMode select

toolMode.coordsys

toolMode.nonUniformScale

toolMode.pivotCenter

toolMode.selectionCenter

toolMode.squashScale

toolMode.transformCenter

toolMode.uniformScale

See also

Trackbar


trackbar const StructDef

3ds max System Globals

trackbar.filter SystemGlobal:filter all

trackbar.GetNextKeyTime

trackbar.GetPreviousKeyTime

trackbar.visible SystemGlobal:visible true

See also

Trackbar

maxOps

ItrackBar


trackView const StructDef

Track View

trackView.clearFilter

trackView.close

trackView.getTrackViewName

trackView.numTrackViews

trackView.open

trackView.pickTrackDlg

trackView.setFilter

trackView.zoomSelected

See also

Trackviews


units const StructDef

3ds max System Globals

units.CustomName SystemGlobal:CustomName FL

units.CustomUnit SystemGlobal:CustomUnit feet

units.CustomValue SystemGlobal:CustomValue 660.0

units.decodeValue

units.DisplayType SystemGlobal:DisplayType Generic

units.formatValue

units.MetricType SystemGlobal:MetricType meters

units.SystemScale SystemGlobal:SystemScale 1.0

units.SystemType SystemGlobal:SystemType inches

units.USFrac SystemGlobal:USFrac frac_1_8

units.USType SystemGlobal:USType ft_Dec_In


viewport const StructDef

Accessing Active Viewport Info, Type, and Transforms

viewport.activeViewport SystemGlobal:activeViewport 4

viewport.GetCamera

viewport.GetLayout

viewport.GetTM

viewport.GetType

viewport.numViews SystemGlobal:numViews 4

viewport.resetAllViews

viewport.SetCamera

viewport.SetLayout

viewport.SetTM

viewport.SetType

viewport.ZoomToBounds

See also

3ds max System Globals

Zoom to Bounds


WAVsound const StructDef

Sound : Helper

WAVsound.end SystemGlobal:end -1.34218e+007f

WAVsound.filename SystemGlobal:filename

WAVsound.isPlaying SystemGlobal:isPlaying false

WAVsound.mute SystemGlobal:mute true

WAVsound.scrub

WAVsound.start SystemGlobal:start -1.34218e+007f


xrefPaths const StructDef

3ds max System Directories

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

xrefs.addNewXRefFile

xrefs.addNewXRefObject

xrefs.attemptUnresolvedXRefs

xrefs.deleteAllXRefs

xrefs.findUnresolvedXRefs

xrefs.getXRefFile

xrefs.getXRefFileCount

xrefs.updateChangedXRefs


New Classes in release 4

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

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

AutomaticAdaptiveExposureControl - superclass: MAXObject

Automatic_Exposure_Control - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

BlendRenderElement - superclass: MAXObject

Combustion.coordinates - superclass: MAXObject

Cone_Angle - superclass: helper

ConeAngleManip - superclass: helper

ConvertToPatch - superclass: modifier

DeletePatch - superclass: modifier

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

Drag - superclass: SpacewarpObject

emissionRenderElement - superclass: MAXObject

FloatList - superclass: FloatController

FloatReactor - superclass: FloatController

Hose - superclass: GeometryClass

HSDS_Modifier - superclass: modifier

HSDSObject - superclass: modifier

imageMotionBlur - superclass: renderEffect

Link - superclass: Matrix3Controller

Link.link_params - superclass: MAXObject

Link_Constraint - superclass: Matrix3Controller

Link_Constraint.link_params - superclass: MAXObject

LinkedXForm - superclass: modifier

LookAt_Constraint - superclass: RotationController

Mesher - superclass: GeometryClass

meshsmooth - superclass: modifier

Motion_Blur - superclass: renderEffect

MultiRes - superclass: modifier

Normalize_Spl - superclass: modifier

Orientation_Constraint - superclass: RotationController

particleMesher - superclass: GeometryClass

Patch_Select - superclass: modifier

Path_Constraint - superclass: PositionController

PDynaflector - superclass: SpacewarpObject

Plane_Angle - superclass: helper

PlaneAngleManip - superclass: helper

Point3List interfaces:

Point3Reactor - superclass: Point3Controller

Point3Spring - superclass: Point3Controller

Point_Cache - superclass: modifier

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

PointCache - superclass: modifier

PointCacheWSM - superclass: SpacewarpModifier

PointHelperObj - superclass: helper

Poly_Select - superclass: modifier

Position_Constraint - superclass: PositionController

PositionList_superclass_PositionController

PositionReactor - superclass: PositionController

PositionSpring - superclass: PositionController

Reflection - superclass: MAXObject

reflectionRenderElement_superclass_MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

RingWave - superclass: GeometryClass

RotationList - superclass: RotationController

RotationReactor - superclass: RotationController

ScaleList - superclass: ScaleController

ScaleReactor - superclass: ScaleController

SDynaflector - superclass: SpacewarpObject

section - superclass: shape

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

sliderManipulator - superclass: helper

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController - superclass: PositionController

transform_script - superclass: Matrix3Controller

Turn_to_Mesh - superclass: modifier

Turn_to_Patch - superclass: modifier

Turn_to_Poly - superclass: modifier

UDynaDeflector - superclass: SpacewarpObject

UVWUnwrap - superclass: modifier

Vortex - superclass: SpacewarpObject

Z_Depth - superclass: MAXObject

ZRenderElement - superclass: MAXObject


Additive_Euler_XYZ - superclass: RotationController

Additive_Euler_XYZ - superclass: RotationController; super-superclass:MAXWrapper - 3:3 - classID: #(8226, 0)

<Additive_Euler_XYZ>.additive_x_rotation Float default: 0.0 -- animatable; float; Controller Scaling: (1 : 57.2958)

<Additive_Euler_XYZ>.additive_y_rotation Float default: 0.0 -- animatable; float; Controller Scaling: (1 : 57.2958)

<Additive_Euler_XYZ>.additive_z_rotation Float default: 0.0 -- animatable; float; Controller Scaling: (1 : 57.2958)


Alpha - superclass: MAXObject

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

Constructor

Alpha ...

Properties

<Alpha>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<Alpha>.elementName String default: "Alpha" -- string

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.

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

See also

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


alphaRenderElement - superclass: MAXObject

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

Constructor

alphaRenderElement ...

Properties

<alphaRenderElement>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<alphaRenderElement>.elementName String default: "Alpha" -- string

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


Atmosphere - superclass: MAXObject

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

Constructor

Atmosphere ...

Properties

<Atmosphere>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<Atmosphere>.elementName String default: "Atmosphere" -- string

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


atmosphereRenderElement - superclass: MAXObject

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

Constructor

Atmosphere ...

Properties

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

Shows whether the element is enabled.

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

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

<atmosphereRenderElement>.elementName String default: "Atmosphere" -- string

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


AutomaticAdaptiveExposureControl - superclass: MAXObject

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

Constructor

AutomaticAdaptiveExposureControl ...

Properties

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

Sets a physical scale for exposure control to use. This is a light intensity value, in candelas. It can range from 0.0 to 200,000.0. The physical scale is factored into light multiplier values, and self-illumination, reflection, and refraction maps. Default=1500.0.

Decreasing the physical scale dims the scene. Increasing the physical scale increases brightness, up to a scale value at which the scene grows no brighter.

This parameter is animatable.

<AutomaticAdaptiveExposureControl>.chromaticAdaptation BooleanClass default: false -- boolean; Chromatic_Adaptation

When the check box is turned on, chromatic adaptation converts all colors so the color displayed in the color swatch appears as white. Default=off.

Clicking the color swatch displays a Color Selector so you can choose the color to adapt to.

Chromatic adaptation is a form of color correction. You can use this control to simulate the eye adjusting to lighting. For example, when the light in a room has a yellow cast, our mind adjusts it so that objects we know to be white, such as printed pages, appear as white.

<AutomaticAdaptiveExposureControl>.colorDiscrimination BooleanClass default: false -- boolean; Color_Discrimination

When on, renders dimly lit colors as if the light were too dim for the eye to distinguish between colors. When on, renders even dimly lit colors. Default=off.

Color differentiation simulates the eye's response to dim lighting. In dim lighting, the eye does not perceive colors and sees tones of gray instead.

The effect of this setting is not apparent except at very low light levels: below 5.62 candelas. This occurs only if the Physical Scale is less than 5.62, if a light's Multiplier is less than 0.00017, or both. When Physical Scale is less than 0.00562, the scene is completely gray.

<AutomaticAdaptiveExposureControl>.whiteColor Color default: (color 255 255 255) -- animatable; RGB color; Color_Discrimination; Controller Scaling: ([1,1,1] : (color 255 255 255))

<AutomaticAdaptiveExposureControl>.exposureValue Float default: 0.0 -- animatable; float; Exposure_Value

Adjusts the overall brightness of the rendering. Can range from -5.0 to 5.0. Negative values make the image darker, and positive values make it brighter. Default=0.0.

The exposure value is comparable to the exposure compensation setting in cameras with automatic exposure.

This parameter is animatable.


Automatic_Exposure_Control - superclass: MAXObject

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

Constructor

Automatic_Exposure_Control ...

Properties

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

Sets a physical scale for exposure control to use. This is a light intensity value, in candelas. It can range from 0.0 to 200,000.0. The physical scale is factored into light multiplier values, and self-illumination, reflection, and refraction maps. Default=1500.0.

Decreasing the physical scale dims the scene. Increasing the physical scale increases brightness, up to a scale value at which the scene grows no brighter.

This parameter is animatable.

<Automatic_Exposure_Control>.chromaticAdaptation BooleanClass default: false -- boolean; Chromatic_Adaptation

When the check box is turned on, chromatic adaptation converts all colors so the color displayed in the color swatch appears as white. Default=off.

Clicking the color swatch displays a Color Selector so you can choose the color to adapt to.

Chromatic adaptation is a form of color correction. You can use this control to simulate the eye adjusting to lighting. For example, when the light in a room has a yellow cast, our mind adjusts it so that objects we know to be white, such as printed pages, appear as white.

<Automatic_Exposure_Control>.colorDiscrimination BooleanClass default: false -- boolean; Color_Discrimination

When on, renders dimly lit colors as if the light were too dim for the eye to distinguish between colors. When on, renders even dimly lit colors. Default=off.

Color differentiation simulates the eye's response to dim lighting. In dim lighting, the eye does not perceive colors and sees tones of gray instead.

The effect of this setting is not apparent except at very low light levels: below 5.62 candelas. This occurs only if the Physical Scale is less than 5.62, if a light's Multiplier is less than 0.00017, or both. When Physical Scale is less than 0.00562, the scene is completely gray.

<Automatic_Exposure_Control>.whiteColor Color default: (color 255 255 255) -- animatable; RGB color; Color_Discrimination; Controller Scaling: ([1,1,1] : (color 255 255 255))

<Automatic_Exposure_Control>.exposureValue Float default: 0.0 -- animatable; float; Exposure_Value

Adjusts the overall brightness of the rendering. Can range from -5.0 to 5.0. Negative values make the image darker, and positive values make it brighter. Default=0.0.

The exposure value is comparable to the exposure compensation setting in cameras with automatic exposure.

This parameter is animatable.

Example:

SceneExposureControl.exposurecontrol = automatic_exposure_control()

SceneExposureControl.exposurecontrol.physicalscale = 800

SceneExposureControl.exposurecontrol.exposurevalue = 0.1


BackgroundRenderElement - superclass: MAXObject

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

Constructor

BackgroundRenderElement ...

Properties

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

Shows whether the element is enabled.

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

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

<BackgroundRenderElement>.elementName String default: "Background" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


bgndRenderElement - superclass: MAXObject

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

Constructor

bgndRenderElement ...

Properties

<bgndRenderElement>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<bgndRenderElement>.elementName String default: "Background" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

bitmapTex interfaces:

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


BlendRenderElement - superclass: MAXObject

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

Constructor

BlendRenderElement

Properties

<BlendRenderElement>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<BlendRenderElement>.elementName String default: "Blend" -- string

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

This control is unavailable when multiple elements are selected.

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

<BlendRenderElement>.atmosphereOn BooleanClass default: true -- boolean

When on, include atmospheric effects. Default=on.

<BlendRenderElement>.shadowOn BooleanClass default: true -- boolean; ShadowsOn

When on, include shadows. Default=on.

<BlendRenderElement>.diffuseOn BooleanClass default: true -- boolean; Diffuse_On

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

<BlendRenderElement>.ambientOn BooleanClass default: true -- boolean; Ambient_On

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

<BlendRenderElement>.specularOn BooleanClass default: true - - boolean; Specular_On

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

<BlendRenderElement>.emissionOn BooleanClass default: true -- boolean; Self_Illumination

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

<BlendRenderElement>.reflectionOn BooleanClass default: true -- boolean; Reflection_On

When on, include reflections. Default=on.

<BlendRenderElement>.refractionOn BooleanClass default: true -- boolean; Refraction_On

When on, include refractions. Default=on.


Combustion.coordinates - superclass: MAXObject

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

Constructor

Combustion.coordinates ...

Properties

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

Affects the sharpness or blurriness of the map based on its distance from the view. The farther away the map is, the greater the blurring. The Blur value blurs maps in world space. Blur is primarily used to avoid aliasing.

<Combustion.coordinates>.mapping Integer default: 0

<Combustion.coordinates>.mapChannel Integer default: 1

<Combustion.coordinates>.mappingType Integer default: 0

<Combustion.coordinates>.phase Float default: 0.0 -- animatable; float

<Combustion.coordinates>.U_Offset Float default: 0.0 -- animatable; float

Changes the position of the map in UV coordinates. The map moves in relation to its size. For example, if you want to shift the map its full width to the left, and half its width downward from its original position, you enter -1 in the U Offset field and 0.5 in the V offset field.

<Combustion.coordinates>.V_Offset Float default: 0.0 -- animatable; float

Changes the position of the map in UV coordinates. The map moves in relation to its size. For example, if you want to shift the map its full width to the left, and half its width downward from its original position, you enter -1 in the U Offset field and 0.5 in the V offset field.

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

Determines the number of times the map is tiled (repeated) along each axis.

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

Determines the number of times the map is tiled (repeated) along each axis.

<Combustion.coordinates>.U_Angle Float default: 0.0 -- animatable; angle; Controller Scaling: (1 : 57.2958)

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

<Combustion.coordinates>.V_Angle Float default: 0.0 -- animatable; angle; Controller Scaling: (1 : 57.2958)

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

<Combustion.coordinates>.W_Angle Float default: 0.0 -- animatable; angle; Controller Scaling: (1 : 57.2958)

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

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

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

<Combustion.coordinates>.Noise_Levels Integer default: 1 -- animatable; integer

<Combustion.coordinates>.Blur_Offset Float default: 0.0 -- animatable; float

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

See also

Combustion

Material Common Properties, Operators, and Methods


Cone_Angle - superclass: helper

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

Constructor

Cone_Angle ...

Properties:

<Cone_Angle>.Origin Point3 default: [0,0,0] -- point3

<Cone_Angle>.Direction Point3 default: [0,0,-1] -- point3

<Cone_Angle>.Angle Float default: 15.0 -- animatable; angle; Controller Scaling: (1 : 57.2958)

The initial angle of the manipulator.

<Cone_Angle>.Distance Float default: 0.0 -- float

The length of the manipulator, in 3ds max units. Default=the distance of mouse drag when the manipulator was created.

<Cone_Angle>.UseSquare BooleanClass default: false -- boolean; Use_Square

When on, the base of the cone is square or rectangular, rather than circular. Default=off.

<Cone_Angle>.Aspect Float default: 1.0 -- float

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

See also

Scripted Manipulators

Interface: manip

radiusManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper

sliderManipulator interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:


ConeAngleManip - superclass: helper

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

Constructor

ConeAngleManip ...

Properties:

<ConeAngleManip>.Origin Point3 default: [0,0,0] -- point3

<ConeAngleManip>.Direction Point3 default: [0,0,-1] -- point3

<ConeAngleManip>.Angle Float default: 15.0 -- animatable; angle; Controller Scaling: (1 : 57.2958)

The initial angle of the manipulator.

<ConeAngleManip>.Distance Float default: 0.0 -- float

The length of the manipulator, in 3ds max units. Default=the distance of mouse drag when the manipulator was created.

<ConeAngleManip>.UseSquare BooleanClass default: false -- boolean; Use_Square

When on, the base of the cone is square or rectangular, rather than circular. Default=off.

<ConeAngleManip>.Aspect Float default: 1.0 -- float

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

See also

Interface: manip

sliderManipulator interfaces:

radiusManip interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper


ConvertToPatch - superclass: modifier

ConvertToPatch - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1011577041, 590161861)

The Turn To Patch modifier lets you apply object conversions in the modifier stack. Using the Turn To Patch modifier, you can fine-tune the conversion process such as turning quads into quad patches.

Note: Converting from one object type to another causes a complete caching in the modifier stack. When you have large objects in your scene, this can take up a lot of space. For example, an object that starts as a mesh, converts to a patch, and then back to a mesh takes 3 times as much space as a mesh which just has ordinary modifiers like Bend or UVW Map applied.

Note: Converting from one object type to another causes a complete caching in the modifier stack. When you have large objects in your scene, this can take up a lot of space. For example, an object that starts as a mesh, converts to a patch, and then back to a mesh takes 3 times as much space as a mesh which just has ordinary modifiers like Bend or UVW Map applied.

Constructor

ConvertToPatch ...

Properties:

<ConvertToPatch>.quadsToQuads BooleanClass default: true -- animatable; boolean; Quads_to_Quad_Patches

Turns quad faces in meshes or polymeshes into quad patches.

<ConvertToPatch>.selectionConversion Integer default: 0 -- integer; Selection_Conversion

<ConvertToPatch>.useSoftSelection Integer default: 1 -- integer; Use_Soft_Selection

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

<ConvertToPatch>.selectionLevel Integer default: 0 -- integer; Selection_Level

These options set the sub-object selection level for passing up the rest of the stack.

0: 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.

1: Object: Uses object as the selection level for passing up the rest of the stack.

2: Edge: Uses edge as the sub-object selection level for passing up the rest of the stack.

3: Vertex: Uses vertex as the sub-object selection level for passing up the rest of the stack.

4: Patch: Uses patch as the sub-object selection level for passing up the rest of the stack.


DeletePatch - superclass: modifier

DeletePatch - superclass: modifier; super-superclass:MAXWrapper - 0:0 - classID: #(2134166570, 0)

Apply the Delete Patch modifier to delete the geometry specified at that sub-object level.


Diffuse - superclass: MAXObject

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

Constructor

Diffuse ...

Properties

<Diffuse>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<Diffuse>.elementName String default: "Diffuse" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


diffuseRenderElement - superclass: MAXObject

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

Constructor

diffuseRenderElement ...

Properties

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

Shows whether the element is enabled.

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

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

<diffuseRenderElement>.elementName String default: "Diffuse" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


emissionRenderElement - superclass: MAXObject

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

Constructor

emissionRenderElement ...

Properties

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

Shows whether the element is enabled.

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

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

<emissionRenderElement>.elementName String default: "Self-Illumination" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Self_Illumination - superclass: MAXObject

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


FloatList - superclass: FloatController

FloatList - superclass: FloatController; super-superclass:MAXWrapper - 1:1 - classID: #(1263210496, 0)

The List controller combines multiple controllers into a single effect. It is a compound controller with tools for managing the order in which its internal controllers are calculated. Controllers are evaluated in a top to bottom order; the controller at the top of the list is evaluated first.

When you assign a List controller to a parameter, the current controller is moved one level below the List controller; it becomes the first controller in the list. A second parameter is added below the List controller and is named Available. This is an empty placeholder for the next controller you add to the list.

Constructor

...

Properties

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

See also

FloatList interfaces:


FloatReactor - superclass: FloatController

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

See also

FloatReactor interfaces:


HSDS_Modifier - superclass: modifier

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

Constructor

HSDS_Modifier ...

Properties

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

Shows the current level of the subdivision hierarchy. Automatically increments when you subdivide a sub-object selection. To edit at a different level of detail, change the setting to the desired level.

<HSDS_Modifier>.matId Integer default: 1 -- integer; Material_Id

Displays the material ID assigned to the current selection. Available only in Polygon and Element sub-object modes. If multiple sub-objects are selected and they don't share an ID, this field is blank.

<HSDS_Modifier>.shadedLattice BooleanClass default: false -- boolean; Shaded_Lattice

Displays only polygons at the current level of detail, with highlights, but without smoothing. Use this option to speed up the display when working with complex objects. Default=off.

<HSDS_Modifier>.ignoreBackface BooleanClass default: false -- boolean; Ignore_Backface

When on, you can select only those sub-objects whose normals are visible in the viewport. When off (the default), selection includes all sub-objects, regardless of the direction of their normals.

<HSDS_Modifier>.useSoftSel BooleanClass default: false -- boolean; Use_Soft_Selection

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

Vertex Interpolation rollout

Determines how selected vertices are treated during subdivision. Available only in Vertex sub-object mode.

For best results, use when moving control grid vertices at a level of detail lower than the highest in which the vertex resides.

<HSDS_Modifier>.useEdgeDist BooleanClass default: false -- boolean; Use_Edge_Distance

<HSDS_Modifier>.affectBackface BooleanClass default: false -- boolean; Affect_Backface

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which they're attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box, but don't want to affect faces on the other side of the object.

Note: Affect Backfacing is not available when editing splines.

When using Edit/Editable Mesh, you can also use the keyboard shortcut CTRL+F to toggle Affect Backfacing (while the Keyboard Shortcut Override Toggle button is turned on).

<HSDS_Modifier>.edgeDistance Integer default: 1 -- integer; Edge_Dist

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

<HSDS_Modifier>.falloff Float default: 20.0 -- float

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry. Default=20.

Note: At the Vertex sub-object level, the region specified by the Falloff setting is depicted graphically in the viewports as a vertex-color gradient from the Sub-selection color (normally red) to the Vertex Ticks color (normally blue). In addition, this gradient is updated in real time as you change the Falloff setting.

<HSDS_Modifier>.pinch Float default: 0.0 -- float

Raises and lowers the top point of the curve along the vertical axis. Sets the relative "pointedness" of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis. Default=0.

<HSDS_Modifier>.bubble Float default: 0.0 -- float

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

<HSDS_Modifier>.vertexType Integer default: 0 -- integer; Vertex_Type]

Standard/Conic/Cusp/Corner:

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

See also

HSDS_Modifier interfaces:


HSDSObject - superclass: modifier

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

Constructor

HSDSObject ...

Properties

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

Shows the current level of the subdivision hierarchy. Automatically increments when you subdivide a sub-object selection. To edit at a different level of detail, change the setting to the desired level.

<HSDSObject>.matId Integer default: 1 -- integer; Material_Id

Displays the material ID assigned to the current selection. Available only in Polygon and Element sub-object modes. If multiple sub-objects are selected and they don't share an ID, this field is blank.

<HSDSObject>.shadedLattice BooleanClass default: false -- boolean; Shaded_Lattice

Displays only polygons at the current level of detail, with highlights, but without smoothing. Use this option to speed up the display when working with complex objects. Default=off.

<HSDSObject>.ignoreBackface BooleanClass default: false -- boolean; Ignore_Backface

When on, you can select only those sub-objects whose normals are visible in the viewport. When off (the default), selection includes all sub-objects, regardless of the direction of their normals.

<HSDSObject>.useSoftSel BooleanClass default: false -- boolean; Use_Soft_Selection

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

Vertex Interpolation rollout

Determines how selected vertices are treated during subdivision. Available only in Vertex sub-object mode.

For best results, use when moving control grid vertices at a level of detail lower than the highest in which the vertex resides.

<HSDSObject>.useEdgeDist BooleanClass default: false -- boolean; Use_Edge_Distance

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

<HSDSObject>.affectBackface BooleanClass default: false -- boolean; Affect_Backface

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which they're attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box, but don't want to affect faces on the other side of the object.

Note: Affect Backfacing is not available when editing splines.

When using Edit/Editable Mesh, you can also use the keyboard shortcut CTRL+F to toggle Affect Backfacing (while the Keyboard Shortcut Override Toggle button is turned on).

<HSDSObject>.edgeDistance Integer default: 1 -- integer; Edge_Dist

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

<HSDSObject>.falloff Float default: 20.0 -- float

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry. Default=20.

Note: At the Vertex sub-object level, the region specified by the Falloff setting is depicted graphically in the viewports as a vertex-color gradient from the Sub-selection color (normally red) to the Vertex Ticks color (normally blue). In addition, this gradient is updated in real time as you change the Falloff setting.

<HSDSObject>.pinch Float default: 0.0 -- float

Raises and lowers the top point of the curve along the vertical axis. Sets the relative "pointedness" of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis. Default=0.

<HSDSObject>.bubble Float default: 0.0 -- float

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

<HSDSObject>.vertexType Integer default: 0 -- integer; Vertex_Type]

Standard/Conic/Cusp/Corner:

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

See also

HSDSObject interfaces:


imageMotionBlur - superclass: renderEffect

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

Constructor

imageMotionBlur ...

Properties

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

Specifies how long the "virtual shutter" is open. When this is set to 1.0, the virtual shutter is open for the entire duration between one frame and the next. The higher the value, the greater the motion Blur effect. Default=1.0.

<imageMotionBlur>.transparency BooleanClass default: true -- boolean

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

See also

imageMotionBlur interfaces:


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.

Constructor

Link ...

Properties

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

<Link>.link_params SubAnim default: SubAnim:Link_Params -- transform

See also

Link.link_params - superclass: MAXObject


Link.link_params - superclass: MAXObject

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

Constructor

Link.link_params ...

Properties

<Link.link_params>.position Point3 default: [0,0,0] -- animatable; point3

<Link.link_params>.rotation Quat default: (quat 0 0 0 1) -- animatable; quat

<Link.link_params>.scale Point3 default: [1,1,1] -- animatable; point3

See also

Link interfaces:

Link - superclass: Matrix3Controller


Link_Constraint - superclass: Matrix3Controller

Link_Constraint - superclass: Matrix3Controller; super-superclass:MAXWrapper - 2:1 - classID: #(-2025855132, -1430354431)

A Link constraint is used to animate an object linking from one target object to another.

The Link constraint causes an object to inherit the position, rotation and scale of its target object.

Constructor

Link_Constraint ...

Properties

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

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:

0: No Key Mode: No keys are created any of the objects involved.

1: Key Nodes: Sets keys for some of the objects.

2: Child: Applied keys to the child object only.

3: Parents: Applies keys to both parents and the child object.

4: Key Entire Hierarchy:This applies keyframes to the chosen nodes and their entire hierarchies.

5: Child: Keys the chosen object and the nodes in its hierarchy up to the world.

6: Parents: Keys both parents and the child and all three hierarchies up to the world.

<Link_Constraint>.link_params SubAnim default: SubAnim:Link_Params -- transform

See also

Link_Constraint.link_params - superclass: MAXObject

Link_Constraint interfaces:


Link_Constraint.link_params - superclass: MAXObject

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

Constructor

Link_Constraint.link_params ...

Properties:

<Link_Constraint.link_params>.position Point3 default: [0,0,0] -- animatable; point3

<Link_Constraint.link_params>.rotation Quat default: (quat 0 0 0 1) -- animatable; quat

<Link_Constraint.link_params>.scale Point3 default: [1,1,1] -- animatable; point3

See also

Link_Constraint interfaces:

Link_Constraint - superclass: Matrix3Controller


LinkedXForm - superclass: modifier

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

Constructor

LinkedXForm ...

Properties

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

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


LookAt_Constraint - superclass: RotationController

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

Constructor

LookAt_Constraint ...

Properties

<LookAt_Constraint>.relative BooleanClass default: false -- boolean

<LookAt_Constraint>.lookat_vector_length Float default: 100.0 -- animatable; float; Vector_Length

<LookAt_Constraint>.set_orientation BooleanClass default: false -- boolean

<LookAt_Constraint>.target_axis Integer default: 2 -- integer

<LookAt_Constraint>.target_axisFlip BooleanClass default: false -- boolean

<LookAt_Constraint>.upnode_axis Integer default: 0 -- integer

<LookAt_Constraint>.upnode_world BooleanClass default: true -- boolean

<LookAt_Constraint>.pickUpNode UndefinedClass default: undefined -- node; Pick_Upnode

<LookAt_Constraint>.StoUP_axis Integer default: 0 -- integer

<LookAt_Constraint>.StoUP_axisFlip BooleanClass default: false -- boolean

<LookAt_Constraint>.viewline_length_abs BooleanClass default: true -- boolean; Viewline_Abs

See also

LookAt_Constraint interfaces:


Mesher - superclass: GeometryClass

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

Constructor

Mesher ...

Properties

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

Click this button and then select the object to be instanced by the Mesher object. After doing so, the name of the instanced object appears on the button.

<Mesher>.renderTimeOnly BooleanClass default: false -- boolean

When on, the Mesher particles do not appear in the viewports, but only when you render the scene. Default=off.

<Mesher>.extranodes ArrayParameter default: #() -- node array

<Mesher>.time Float default: 0.0 -- float

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

<Mesher>.radius Float default: 10.0 -- float

<Mesher>.useCustomBounds BooleanClass default: false -- boolean; Use_Custom_Bounds

When on, Mesher replaces the dynamic bounding box derived from the particle system and modifier with a static bounding box of the user's choice.

<Mesher>.boundsMin Point3 default: [1,1,1] -- point3; BoundsA

<Mesher>.boundsMax Point3 default: [-1,-1,-1] -- point3; BoundsB

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

See also

Mesher

particleMesher - superclass: GeometryClass


meshsmooth - superclass: modifier

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

Constructor

meshsmooth ...

Properties:

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

Selects the Subdivision method to use:

0: Classic (Produces three- and four-sided facets.)

1: Quad Output (Produces only four-sided facets.)

2: NURMS (Produces Non-Uniform Rational MeshSmooth object.)

<meshsmooth>.ignoreSel BooleanClass default: true -- boolean; Apply_To_Whole_Mesh

When turned on, any sub-object selection passed up the stack is ignored and MeshSmooth is applied to the entire object.

<meshsmooth>.oldMapping BooleanClass default: false -- boolean; Old_style_Mapping

Uses the algorithm from the previous release of the program to apply MeshSmooth to the mapping coordinates. This technique tends to distort the underlying mapping coordinates as it creates new faces and as texture coordinates shift.

<meshsmooth>.iterations Integer default: 0 -- animatable; integer

The number of iterations used to smooth the mesh. Each iteration generates new faces using the vertices created from the previous iteration.

<meshsmooth>.smoothness Float default: 1.0 -- animatable; float; Smoothness_Filter

Determines how sharp a corner must be before faces are added to smooth it. Smoothness is calculated as the average angle of all edges connected to a vertex. A value of 0.0 prevents the creation of any faces. A value of 1.0 adds faces to all vertices even if they lie on a plane.

<meshsmooth>.useRenderIterations BooleanClass default: false -- boolean; Use_Render_Iterations

Turn on/off use of render iterations, for using a different number of iterations at render time. When off, the software will use the iterations value.

<meshsmooth>.renderItSerations Integer default: 0 -- animatable; integer; Render_Iterations

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

<meshsmooth>.useRenderSmoothness BooleanClass default: false -- boolean; Use_Render_Smoothness

Turn on/off use of render smoothness, for using a different smoothness value at render time. When off, the software will use the smoothness value.

<meshsmooth>.renderSmoothness Float default: 1.0 -- animatable; float; Render_Smoothness

Lets you choose a different Smoothness value to be applied to the object at render time.

<meshsmooth>.faceType Integer default: 1 -- integer; Face_Type

Select the type to operate on during input conversion:

0: Faces

1: Polygons

Operate On Faces treats every triangle as a face and smooths across all edges, even invisible edges. Operate On Polygons ignores invisible edges, treating polygons (like the quads making up a box or the cap on a cylinder) as a single face.

<meshsmooth>.keepConvex BooleanClass default: false -- boolean; Keep_Input_Faces_Convex

Keeps all input polygons convex. Selecting this option causes non-convex polygons to be handled as a minimum number of separate faces, each of which is convex.

<meshsmooth>.update Integer default: 0 -- integer; Update_Options

Set update options:

0: Always update

1: Update when rendering

2: Update Manually

<meshsmooth>.limitSurface BooleanClass default: false -- boolean; Project_to_Limit_Surface

Places all points on the "limit surface" of the MeshSmooth result, which is the surface you'd get after an infinite number of iterations.

<meshsmooth>.smoothResult BooleanClass default: true -- boolean; Smooth_Output

Applies the same smoothing group to all faces.

<meshsmooth>.sepByMats BooleanClass default: false -- boolean; Separate_By_Materials

Prevents the creation of new faces for edges between faces that do not share Material IDs.

<meshsmooth>.sepBySmGroups BooleanClass default: false -- boolean; Separate_By_Smoothing_Group

Prevents the creation of new faces at edges between faces that don't share at least one smoothing group.

<meshsmooth>.ignoreBackfacing BooleanClass default: false -- boolean; Ignore_Backfacing

When on, selection of sub-objects selects only those sub-objects whose normals are visible in the viewport. When off (the default), selection includes all sub-objects, regardless of the direction of their normals.

<meshsmooth>.displayCage BooleanClass default: false -- boolean; Display_Control_Mesh

Displays an orange wireframe gizmo that shows what the control mesh looks like after it's been converted to polygons (if applicable) and before the smoothing occurs.

<meshsmooth>.controlLevel Integer default: 0 -- integer; Control_Level

Allows you to see the control mesh after one or more iterations and to edit sub-object points and edges at that level.

<meshsmooth>.useSoftSel BooleanClass default: false -- boolean; Use_Soft_Selection

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

<meshsmooth>.useEdgeDist BooleanClass default: false -- boolean; Use_Edge_Distance

Turn on/off use Edge Distance.

<meshsmooth>.edgeDist Integer default: 1 -- integer; Edge_Distance

Limits the region affected by the number of edges between the selection and the affected vertices.

<meshsmooth>.affectBackfacing BooleanClass default: false -- boolean; Affect_Backfacing

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which they're attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence.

<meshsmooth>.falloff Float default: 20.0 -- float

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry.

<meshsmooth>.pinch Float default: 0.0 -- float

Raises and lowers the top point of the curve along the vertical axis. Sets the relative "pointedness" of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis.

<meshsmooth>.bubble Float default: 0.0 -- float

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

<meshsmooth>.reset Integer default: 1 -- integer; Update_Options

Select reset settings:

0: Reset all levels

1: Reset this level

See also

MeshSmooth : Modifier

Modifier and SpacewarpModifier Types


Motion_Blur - superclass: renderEffect

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

Constructor

Motion_Blur ...

Properties

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

Specifies how long the "virtual shutter" is open. When this is set to 1.0, the virtual shutter is open for the entire duration between one frame and the next. The higher the value, the greater the motion Blur effect. Default=1.0.

<Motion_Blur>.transparency BooleanClass default: true -- boolean

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

See also

Motion_Blur interfaces:


Normalize_Spl - superclass: modifier

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

Constructor

Normalize_Spl ...

Properties

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

Determines how many control points are added. Smaller values produce more control points; larger values produce fewer.

The positions of the original vertices are disregarded. Vertices are set to regular intervals once the Normalize Spline modifier is applied.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Orientation_Constraint - superclass: RotationController

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

Constructor

Orientation_Constraint ...

Properties

<Orientation_Constraint>.relative BooleanClass default: false -- boolean

<Orientation_Constraint>.local_world Integer default: 0 -- integer; LocalOrWorld

See also

Orientation_Constraint interfaces:


particleMesher - superclass: GeometryClass

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

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

Constructor

particleMesher ...

Properties

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

Click this button and then select the object to be instanced by the Mesher object. After doing so, the name of the instanced object appears on the button.

<particleMesher>.renderTimeOnly BooleanClass default: false -- boolean

When on, the Mesher particles do not appear in the viewports, but only when you render the scene. Default=off.

Use this option to reduce the amount of computation required for the viewport display.

<particleMesher>.extranodes ArrayParameter default: #() -- node array

<particleMesher>.time Float default: 0.0 -- float

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

<particleMesher>.radius Float default: 10.0 -- float

<particleMesher>.useCustomBounds BooleanClass default: false -- boolean; Use_Custom_Bounds

When on, Mesher replaces the dynamic bounding box derived from the particle system and modifier with a static bounding box of the user's choice.

<particleMesher>.boundsMin Point3 default: [1,1,1] -- point3; BoundsA

<particleMesher>.boundsMax Point3 default: [-1,-1,-1] -- point3; BoundsB

See also

Mesher

Mesher - superclass: GeometryClass


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

patch const StructDef

patchOps const StructDef

Patch : GeometryClass


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 frame where you want the key set, and adjust the % Along Path spinner to move the object.

<Path_Constraint>.follow BooleanClass default: false -- boolean

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

<Path_Constraint>.path UndefinedClass default: undefined -- node; Path_Constraint

Add Path: is used to add a new spline path that influences the constrained object.

Delete path: is used to remove a path from the target list. Once removing the path target, it will no longer influence the constrained object

<Path_Constraint>.bank BooleanClass default: false -- boolean

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

<Path_Constraint>.bankAmount Float default: 0.5 -- animatable; float; Bank_Amount

Adjusts the amount of the banking to one side or the other, depending on whether the value is positive or negative

<Path_Constraint>.smoothness Float default: 0.5 -- animatable; float

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

<Path_Constraint>.allowUpsideDown BooleanClass default: false -- boolean; Allow_Upside_Down

Turn on to avoid the situation in which an object flips when going around a vertically oriented path.

<Path_Constraint>.constantVel BooleanClass default: false -- boolean; Constant_Velocity

Provides a constant velocity along the path. When off, the velocity of the object along the path varies depending on the distance between the vertices on the path.

<Path_Constraint>.axis Integer default: 0 -- integer

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

<Path_Constraint>.axisFlip BooleanClass default: false -- boolean; Axis_Flip

Turn on to flip the direction of the axis

<Path_Constraint>.loop BooleanClass default: false -- boolean

By default, when the constrained object reaches the end of a path it can no longer move past the end point. The loop option changes this behavior so that when the constrained object reaches the end of the path it loops back to the starting point.

<Path_Constraint>.relative BooleanClass default: false -- boolean

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

See also

Path_Constraint interfaces:


PDynaflector - superclass: SpacewarpObject

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

Constructor

...

Properties

<PDynaflector>.'time on' Integer default: 0 -- animatable; integer; Time_On

<PDynaflector>.'time off' Integer default: 16000 -- animatable; integer; Time_Off

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

<PDynaflector>.bounce Float default: 1.0 -- animatable; float

<PDynaflector>.bouncevar Float default: 0.0 -- animatable; percentage; Bounce_Variation; Controller Scaling: (1 : 100.0)

<PDynaflector>.chaos Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)

<PDynaflector>.inheritVelocity Float default: 1.0 -- animatable; float; Velocity_Inheritance

<PDynaflector>.width Float default: 0.0 -- animatable; float

<PDynaflector>.height Float default: 0.0 -- animatable; float

<PDynaflector>.mass Float default: 1.0 -- animatable; float; Particle_Mass

<PDynaflector>.'mass units' Integer default: 0 -- radio button number; Particle_Mass_Units

<PDynaflector>.number Integer default: 0 -- animatable; integer; Number_of_Particles

<PDynaflector>.friction Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)


Plane_Angle - superclass: helper

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

Constructor

Plane_Angle ...

Properties

<Plane_Angle>.Origin Point3 default: [0,0,0] -- point3

<Plane_Angle>.NormalVec Point3 default: [0,0,1] -- point3; Normal_Vector

<Plane_Angle>.UpVec Point3 default: [0,1,0] -- point3; Up_Vector

<Plane_Angle>.Angle Float default: 0.0 -- animatable; angle; Controller Scaling: (1 : 57.2958)

The angle of the manipulator, from 0.0 to 360.0 (both values are perpendicular in the Y axis of the viewport where you created the manipulator, unless you have rotated the manipulator object). Default=0.0.

<Plane_Angle>.Distance Float default: 0.0 -- float

The length of the manipulator, in 3ds max units. Default=the distance of mouse drag when the manipulator was created.

<Plane_Angle>.Size Float default: 1.0 -- float

The size of the manipulator's handle, in 3ds max units. Default=1.0.

See also

Scripted Manipulators

Interface: manip

sliderManipulator interfaces:

radiusManip interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper


PlaneAngleManip - superclass: helper

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

Constructor

PlaneAngleManip ...

Properties

<PlaneAngleManip>.Origin Point3 default: [0,0,0] -- point3

<PlaneAngleManip>.NormalVec Point3 default: [0,0,1] -- point3; Normal_Vector

<PlaneAngleManip>.UpVec Point3 default: [0,1,0] -- point3; Up_Vector

<PlaneAngleManip>.Angle Float default: 0.0 -- animatable; angle; Controller Scaling: (1 : 57.2958)

The angle of the manipulator, from 0.0 to 360.0 (both values are perpendicular in the Y axis of the viewport where you created the manipulator, unless you have rotated the manipulator object). Default=0.0.

<PlaneAngleManip>.Distance Float default: 0.0 -- float

The length of the manipulator, in 3ds max units. Default=the distance of mouse drag when the manipulator was created.

<PlaneAngleManip>.Size Float default: 1.0 -- float

The size of the manipulator's handle, in 3ds max units. Default=1.0.

See also

Scripted Manipulators

Interface: manip

sliderManipulator interfaces:

radiusManip interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper


Point3List - superclass: Point3Controller

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

Constructor

Point3List ...

Properties

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

See also

Point3List interfaces:


Point3Reactor - superclass: Point3Controller

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

See also

Point3Reactor interfaces:


Point3Spring - superclass: Point3Controller

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

Constructor

Point3Spring ...

Properties:

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

<Point3Spring>.x_effect Float default: 100.0

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

<Point3Spring>.y_effect Float default: 100.0

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

<Point3Spring>.z_effect Float default: 100.0

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

See also

PositionSpring interfaces:

Point3Spring interfaces:

SpringPoint3Controller interfaces:

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController interfaces:

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex interfaces:

flexOps const StructDef


Point_Cache - superclass: modifier

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

Constructor

Point_Cache ...

Properties

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

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

The frame number at which the cached animation starts playing back. Using decimal fractions lets you start at a sub-frame setting when using a Frame:Ticks time display. Default=0.0.

Sets the first frame for recording the vertex animation.

<Point_Cache>.end_time Float default: 100.0 -- float

Sets the last frame for recording the vertex animation.

<Point_Cache>.samples Integer default: 1 -- integer

<Point_Cache>.cache_file UndefinedClass default: undefined -- string

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

<Point_Cache>.relativeOffset BooleanClass default: false -- boolean; Relative_Offset

Makes the Strength setting available. This enables offsetting the animated vertex positions relative to their positions as recorded. Default=off.

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

<Point_Cache>.strength Float default: 1.0 -- animatable; float

Affects the motion relative to the original animation. Available only when Use Relative Offsets is turned on. Default=1.0. Range=-10.0 to 10.0.

At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1, the animation is relatively restrained. At strengths greater than 1, the animation is exaggerated. With negative Strength settings, the motion is reversed.

See also

Point Cache Modifier

Point_Cache interfaces:

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

Point_CacheSpacewarpModifier interfaces:


Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

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

Constructor

Point_CacheSpacewarpModifier ...

Properties

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

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

The frame number at which the cached animation starts playing back. Using decimal fractions lets you start at a sub-frame setting when using a Frame:Ticks time display. Default=0.0.

Sets the first frame for recording the vertex animation.

<Point_CacheSpacewarpModifier>.end_time Float default: 100.0 -- float

Sets the last frame for recording the vertex animation.

<Point_CacheSpacewarpModifier>.samples Integer default: 1 -- integer

<Point_CacheSpacewarpModifier>.cache_file UndefinedClass default: undefined -- string

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

<Point_CacheSpacewarpModifier>.relativeOffset BooleanClass default: false -- boolean; Relative_Offset

Makes the Strength setting available. This enables offsetting the animated vertex positions relative to their positions as recorded. Default=off.

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

<Point_CacheSpacewarpModifier>.strength Float default: 1.0 -- animatable; float

Affects the motion relative to the original animation. Available only when Use Relative Offsets is turned on. Default=1.0. Range=-10.0 to 10.0.

At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1, the animation is relatively restrained. At strengths greater than 1, the animation is exaggerated. With negative Strength settings, the motion is reversed.

See also

Point Cache Modifier

Point_Cache interfaces:

Point_Cache - superclass: modifier

Point_CacheSpacewarpModifier interfaces:


PointCache - superclass: modifier

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

Constructor

PointCache ...

Properties

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

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

The frame number at which the cached animation starts playing back. Using decimal fractions lets you start at a sub-frame setting when using a Frame:Ticks time display. Default=0.0.

Sets the first frame for recording the vertex animation.

<PointCache>.end_time Float default: 100.0 -- float

Sets the last frame for recording the vertex animation.

<PointCache>.samples Integer default: 1 -- integer

<PointCache>.cache_file UndefinedClass default: undefined -- string

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

<PointCache>.relativeOffset BooleanClass default: false -- boolean; Relative_Offset

Makes the Strength setting available. This enables offsetting the animated vertex positions relative to their positions as recorded. Default=off.

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

<PointCache>.strength Float default: 1.0 -- animatable; float

Affects the motion relative to the original animation. Available only when Use Relative Offsets is turned on. Default=1.0. Range=-10.0 to 10.0.

At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1, the animation is relatively restrained. At strengths greater than 1, the animation is exaggerated. With negative Strength settings, the motion is reversed.

See also

Point Cache Modifier

Point_Cache interfaces:

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

Point_CacheSpacewarpModifier interfaces:


PointCacheWSM - superclass: SpacewarpModifier

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

Constructor

PointCacheWSM ...

Properties

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

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

The frame number at which the cached animation starts playing back. Using decimal fractions lets you start at a sub-frame setting when using a Frame:Ticks time display. Default=0.0.

Sets the first frame for recording the vertex animation.

<PointCacheWSM>.end_time Float default: 100.0 -- float

Sets the last frame for recording the vertex animation.

<PointCacheWSM>.samples Integer default: 1 -- integer

<PointCacheWSM>.cache_file UndefinedClass default: undefined -- string

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

<PointCacheWSM>.relativeOffset BooleanClass default: false -- boolean; Relative_Offset

Makes the Strength setting available. This enables offsetting the animated vertex positions relative to their positions as recorded. Default=off.

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

<PointCacheWSM>.strength Float default: 1.0 -- animatable; float

Affects the motion relative to the original animation. Available only when Use Relative Offsets is turned on. Default=1.0. Range=-10.0 to 10.0.

At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1, the animation is relatively restrained. At strengths greater than 1, the animation is exaggerated. With negative Strength settings, the motion is reversed.

See also

Point Cache Modifier

Point_Cache interfaces:

Point_Cache - superclass: modifier

Point_CacheSpacewarpModifier interfaces:


PointHelperObj - superclass: helper

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

Constructor

PointHelperObj ...

Properties

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

Sets the size for the point object. Use this to minimize the point object, or increase its size to aid in locating it. Default=20.

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

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

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

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

<PointHelperObj>.cross BooleanClass default: true -- animatable; boolean

Displays an axis-aligned cross.

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

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

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

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

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

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

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Poly_Select - superclass: modifier

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

Constructor

Poly_Select ...

Properties

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

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

You can also use the keyboard shortcut CTRL+S to toggle Use Soft Selection (while the Plug-In Keyboard Shortcut Toggle button is turned on).

<Poly_Select>.softselUseEdgeDistance BooleanClass default: false -- boolean; Use_Edge_Distance

<Poly_Select>.softselEdgeDist Integer default: 1 -- animatable; integer; Edge_Distance

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

<Poly_Select>.softselAffectBackfacing BooleanClass default: false -- boolean; Affect_Backfacing

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which they're attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box, but don't want to affect faces on the other side of the object.

You can also use the keyboard shortcut CTRL+F to toggle Affect Backfacing (while the Plug-In Keyboard Shortcut Toggle button is turned on).

<Poly_Select>.softselFalloff Float default: 20.0 -- animatable; world units; Falloff

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry. Default=20.

Note: At the Vertex sub-object level, the region specified by the Falloff setting is depicted graphically in the viewports as a vertex-color gradient from the Sub-selection color (normally red) to the Vertex Ticks color (normally blue). In addition, this gradient is updated in real time as you change the Falloff setting.

<Poly_Select>.softselPinch Float default: 0.0 -- animatable; float; Pinch

Raises and lowers the top point of the curve along the vertical axis. Sets the relative "pointedness" of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis. Default=0.

<Poly_Select>.softselBubble Float default: 0.0 -- animatable; float; Bubble

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


Position_Constraint - superclass: PositionController

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

Constructor

Position_Constraint ...

Properties:

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

See also

Position_Constraint interfaces:


PositionList - superclass: PositionController

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

Constructor

PositionList ...

Properties:

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

See also

PositionList interfaces:


PositionReactor - superclass: PositionController

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

See also

PositionReactor interfaces:


PositionSpring - superclass: PositionController

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

Constructor

PositionSpring ...

Properties

<PositionSpring>.effectHow Integer default: 1 -- radio button number; Abs_Rel

<PositionSpring>.forceNode ArrayParameter default: #() -- node array; Force_Nodes; SubAnim

<PositionSpring>.steps Integer default: 2 -- integer

<PositionSpring>.x_effect Float default: 100.0 -- animatable; float

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

<PositionSpring>.y_effect Float default: 100.0 -- animatable; float

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

<PositionSpring>.z_effect Float default: 100.0 -- animatable; float

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

<PositionSpring>.start Integer default: 0 -- integer; Start_Frame

<PositionSpring>.position Point3 default: [0,0,0] -- animatable; point3

See also

PositionSpring interfaces:

Point3Spring interfaces:

SpringPoint3Controller interfaces:

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController interfaces:

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex interfaces:

flexOps const StructDef


Reflection - superclass: MAXObject

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

Constructor

Reflection ...

Properties

<Reflection>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<Reflection>.elementName String default: "Reflection" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


reflectionRenderElement - superclass: MAXObject

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

Constructor

reflectionRenderElement ...

Properties

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

Shows whether the element is enabled.

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

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

<reflectionRenderElement>.elementName String default: "Reflection" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


Refraction - superclass: MAXObject

Refraction - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(7, 0)

Constructor

Refraction ...

Properties

<Refraction>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<Refraction>.elementName String default: "Refraction" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


refractionRenderElement - superclass: MAXObject

refractionRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(7, 0)

Constructor

refractionRenderElement ...

Properties

<refractionRenderElement>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<refractionRenderElement>.elementName String default: "Refraction" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


RingWave - superclass: GeometryClass

RingWave - superclass: GeometryClass; super-superclass:node - 26:0 - classID: #(686038884, 306926354)


RotationList - superclass: RotationController

RotationList - superclass: RotationController; super-superclass:MAXWrapper - 1:1 - classID: #(1263210499, 0)

Constructor

RotationList ...

Properties

<RotationList>.available Quat default: (quat 0 0 0 1) -- animatable; quat

See also

RotationList interfaces:


RotationReactor - superclass: RotationController

RotationReactor - superclass: RotationController; super-superclass:MAXWrapper - 0:0 - classID: #(713503979, 1475640742)

See also

RotationReactor interfaces:


ScaleList - superclass: ScaleController

ScaleList - superclass: ScaleController; super-superclass:MAXWrapper - 1:1 - classID: #(1263210500, 0)

Constructor

ScaleList ...

Properties

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

See also

ScaleList interfaces:


ScaleReactor - superclass: ScaleController

ScaleReactor - superclass: ScaleController; super-superclass:MAXWrapper - 0:0 - classID: #(331629852, 751514504)

See also

ScaleReactor interfaces:


SDynaflector - superclass: SpacewarpObject

SDynaflector - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID: #(1147744028, 332006682)

Constructor

...

Properties

<SDynaflector>.'time on' Integer default: 0 -- animatable; integer; Time_On

<SDynaflector>.'time off' Integer default: 16000 -- animatable; integer; Time_Off

<SDynaflector>.affects Float default: 10000.0 -- animatable; percentage; Reflects; Controller Scaling: (1 : 100.0)

<SDynaflector>.bounce Float default: 1.0 -- animatable; float

<SDynaflector>.bouncevar Float default: 0.0 -- animatable; percentage; Bounce_Variation; Controller Scaling: (1 : 100.0)

<SDynaflector>.chaos Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)

<SDynaflector>.inheritVelocity Float default: 1.0 -- animatable; float; Velocity_Inheritance

<SDynaflector>.radius Float default: 0.0 -- animatable; float

<SDynaflector>.mass Float default: 1.0 -- animatable; float; Particle_Mass

<SDynaflector>.'mass units' Integer default: 0 -- radio button number; Particle_Mass_Units

<SDynaflector>.number Integer default: 0 -- animatable; integer; Number_of_Particles

<SDynaflector>.friction Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)


section - superclass: shape

section - superclass: shape; super-superclass:node - 13:0 - classID: #(549004141, 1725569194)

Constructor

section ...

Properties:

<section>.angle Float default: 0.0 -- float

<section>.renderable BooleanClass default: false -- boolean

<section>.mapCoords BooleanClass default: false -- boolean

<section>.thickness Float default: 1.0 -- float

<section>.sides Float default: 12.0 -- integer

<section>.viewport_thickness Float default: 1.0 -- float

<section>.viewport_sides Integer default: 12 -- integer

<section>.viewport_angle Float default: 0.0 -- float

<section>.DisplayRenderMesh BooleanClass default: false -- boolean

<section>.UseViewportSettings BooleanClass default: false -- boolean

<section>.DisplayRenderSettings BooleanClass default: true -- boolean

Note: 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; super-superclass:Value - 4:0 - classID: #(5, 0)

Constructor

Self_Illumination ...

Properties

<Self_Illumination>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<Self_Illumination>.elementName String default: "Self-Illumination" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

emissionRenderElement - superclass: MAXObject

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


ShadowRenderElement - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(8, 0)

Constructor

ShadowRenderElement ...

Properties

<ShadowRenderElement>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<ShadowRenderElement>.elementName String default: "Shadow" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

Specular - superclass: MAXObject

specularRenderElement - superclass: MAXObject


sliderManipulator - superclass: helper

sliderManipulator - superclass: helper; super-superclass:node - 10:0 - classID: #(1205540079, 1318803856)

Constructor

sliderManipulator ...

Properties

<sliderManipulator>.value Float default: 0.0 -- animatable; float

The value of the slider, based on the position of the slidable triangle. Default=0.0.

<sliderManipulator>.minVal Float default: 0.0 -- animatable; float

The minimum possible value of the slider. Default=0.0.

<sliderManipulator>.maxVal Float default: 100.0 -- animatable; float

The maximum possible value of the slider. Default=100.0.

When the minimum is 0.0 and the maximum is 100.0, the slider Value can represent a percentage.

<sliderManipulator>.xPos Float default: 0.0 -- float

The slider's X location in the active viewport. Default=Viewport X location you clicked when you created the slider.

<sliderManipulator>.yPos Float default: 0.0 -- float

The slider's Y location in the active viewport. Default=Viewport Y location you clicked when you created the slider.

<sliderManipulator>.width Float default: 100.0 -- float

The slider's width, in 3ds max units. Default=100.0.

<sliderManipulator>.hide BooleanClass default: false -- boolean

When on, hides all of the slider except for the label and the move and show/hide components. Default=off.

<sliderManipulator>.sldName String default: "" -- string

The slider label that appears in viewports. Default=none.

<sliderManipulator>.snapToggle BooleanClass default: true -- boolean

When on, the slider "snaps" to incremental values. When off, Default=on.

<sliderManipulator>.snapVal Float default: 0.01 -- float

The increment used by the slider when Snap is on. Default=0.01.

See also

Scripted Manipulators

Interface: manip

radiusManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper

sliderManipulator interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:


Specular - superclass: MAXObject

Specular - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(2, 0)

Constructor

Specular ...

Properties

<Specular>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<Specular>.elementName String default: "Specular" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

specularRenderElement - superclass: MAXObject


specularRenderElement - superclass: MAXObject

specularRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(2, 0)

Constructor

specularRenderElement ...

Properties

<specularRenderElement>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

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

<specularRenderElement>.elementName String default: "Specular" -- string

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

This control is unavailable when multiple elements are selected.

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

See also

Alpha - superclass: MAXObject

alphaRenderElement - superclass: MAXObject

Atmosphere - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject

Diffuse - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject

Reflection - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject

Refraction - superclass: MAXObject

refractionRenderElement - superclass: MAXObject

Self_Illumination - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject

Specular - superclass: MAXObject specularRenderElement_superclass_MAXObject


SpringPoint3Controller - superclass: Point3Controller

SpringPoint3Controller - superclass: Point3Controller; super-superclass:MAXWrapper - 4:4 - classID: #(327754098, 1754751609)

Constructor

SpringPoint3Controller ...

Properties:

<SpringPoint3Controller>.position Point3 default: [0,0,0] -- animatable; point3

<SpringPoint3Controller>.x_effect Float default: 100.0

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

<SpringPoint3Controller>.y_effect Float default: 100.0

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

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

Point3Spring interfaces:

SpringPoint3Controller interfaces:

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController interfaces:

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex interfaces:

flexOps const StructDef


SpringPositionController - superclass: PositionController

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

Constructor

SpringPositionController ...

Properties:

<SpringPositionController>.effectHow Integer default: 1 -- radio button number; Abs_Rel

<SpringPositionController>.forceNode ArrayParameter default: #() -- node array; Force_Nodes; SubAnim

<SpringPositionController>.steps Integer default: 2 -- integer

<SpringPositionController>.x_effect Float default: 100.0 -- animatable; float

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

<SpringPositionController>.y_effect Float default: 100.0 -- animatable; float

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

<SpringPositionController>.z_effect Float default: 100.0 -- animatable; float

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

<SpringPositionController>.start Integer default: 0 -- integer; Start_Frame

<SpringPositionController>.position Point3 default: [0,0,0] -- animatable; point3

See also

PositionSpring interfaces:

Point3Spring interfaces:

SpringPoint3Controller interfaces:

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController interfaces:

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex interfaces:

flexOps const StructDef


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.

The software interprets the text you type into the Script text box as the body of a MAXScript block expression. You can type as many expressions as you want on as many lines as you want, and they are evaluated in turn. The value of the last expression is taken as the controller value. This must yield a matrix3 value for Transform Script controllers.

Since the text is inside a block expression, you can declare local variables which are visible only within the script and are temporary for one evaluation. You can also declare or access global variables that are shared with all other scripts in MAXScript and hold their values from one evaluation to the next.

A controller is always evaluated by the software with respect to a specific animation time. This might be the current time slider or incrementing frame time if an animation is playing, or a rendering is under way. In the case of Script controllers, the time being evaluated is used to establish an automatic "at time" context around the controller script, so any properties you access (outside of other explicit "at time" expressions) yield the correct values for the current controller evaluation time. This means you don't have to do anything special in your scripts to work at the correct time. You can access the evaluation time, with the standard MAXScript variable, current Time. You can also reference scene property values at other times by using "at time" expressions in your scripts, as in regular MAXScript programming.

Constructor

transform_script ...

Properties

<transform_script>.script String default: "(matrix3 1)"

See also

Script Controllers


Turn_to_Mesh - superclass: modifier

Turn_to_Mesh - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1549488375, 1614380193)

Constructor

Turn_to_Mesh ...

Properties

<Turn_to_Mesh>.useInvisibleEdges BooleanClass default: true -- animatable; boolean; Use_Invisible_Edges

When on, uses invisible edges to represent polygons. When off, produces a completely triangulated mesh with all visible edges. Default=on.

<Turn_to_Mesh>.selectionConversion Integer default: 0 -- integer; Selection_Conversion

<Turn_to_Mesh>.useSoftSelection BooleanClass default: true -- boolean; Use_Soft_Selection

Affects the action of sub-object Move, Rotate, and Scale functions. When these are on, 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 poly, and you apply Turn To Mesh with Include Soft Selection on, then the same soft selection will apply to the mesh vertices. Default=on.

For more information, see Soft Selection Rollout.

Important: Be aware that when Include Soft Selection is on, bound vertices can turn to meshes.

<Turn_to_Mesh>.selectionLevel Integer default: 0 -- integer; Selection_Level

0: 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.

1: Object. Uses object as the selection level for passing up the rest of the stack.

2: Edge. Uses edge as the sub-object selection level for passing up the rest of the stack.

3: Vertex. Uses vertex as the sub-object selection level for passing up the rest of the stack.

4: 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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Turn_to_Patch - superclass: modifier

Turn_to_Patch - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1011577041, 590161861)

Constructor

Turn_to_Patch ...

Properties

<Turn_to_Patch>.quadsToQuads BooleanClass default: true -- animatable; boolean; Quads_to_Quad_Patches

Turns quad faces in meshes or polymeshes into quad patches.

Note: When you turn this option off, 3ds max triangulates quads when the Turn To Patch modifier is applied to a patch object.

<Turn_to_Patch>.selectionConversion Integer default: 0 -- integer; Selection_Conversion

<Turn_to_Patch>.useSoftSelection Integer default: 1 -- integer; Use_Soft_Selection

Affects the action of sub-object Move, Rotate, and Scale functions. When these are on, 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 poly, and you apply Turn To Mesh with Include Soft Selection on, then the same soft selection will apply to the mesh vertices. Default=on.

For more information, see Soft Selection Rollout.

Important: Be aware that when Include Soft Selection is on, bound vertices can turn to meshes.

<Turn_to_Patch>.selectionLevel Integer default: 0 -- integer; Selection_Level

0: 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.

1: Object. Uses object as the selection level for passing up the rest of the stack.

2: Edge. Uses edge as the sub-object selection level for passing up the rest of the stack.

3: Vertex. Uses vertex as the sub-object selection level for passing up the rest of the stack.

4: 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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Turn_to_Poly - superclass: modifier

Turn_to_Poly - superclass: modifier; super-superclass:MAXWrapper - 9:0 - classID: #(793333328, 1547135298)

Constructor

Turn_to_Poly ...

Properties:

<Turn_to_Poly>.keepConvex BooleanClass default: false -- animatable; boolean; Keep_Convex

Does not join across edges if the resulting polygon would not be convex. "Convex" means that you can connect any two points in the polygon with a line that doesn't go outside the polygon. A polygon is not convex if you can draw a line between vertices and that line lays outside of the polygon.

Problems that can occur with non-convex polygons include the fact that changes in the geometry of the input object can result in a different topology for the Turn To Poly result. For instance, in a box, if you drag one of the top corners across the middle of the top face, the box becomes non-convex. Turn To Poly would then see this as two triangles instead of one quad, and the number of points in the result would change.

<Turn_to_Poly>.limitPolySize BooleanClass default: false -- animatable; boolean; Limit_Polygon_Size

Limits the number of sides to a polygon so that the surface is better defined. For example, you might want to produce a polymesh of triangles and quads, or one composed of all triangles, rather than joining together more than two triangles into pentagons, hexagons, and so on.

<Turn_to_Poly>.maxPolySize Integer default: 4 -- animatable; integer; Max_Polygon_Size

The maximum number of sides to a polygon.

<Turn_to_Poly>.requirePlanar BooleanClass default: false -- animatable; boolean; Require_Planar_Polygons

Creates polygons composed of flat planes. Does not join faces together across an edge if the edge has a sharper angle than the threshold listed.

<Turn_to_Poly>.planarThresh Float default: 15.0 -- animatable; angle; Planar_Threshold; Controller Scaling: (1 : 57.2958)

Controls the threshold of the angle between polygonal planes.

<Turn_to_Poly>.removeMidEdgeVertices BooleanClass default: true -- boolean; Remove_Mid_Edge_Vertices

<Turn_to_Poly>.selectionConversion Integer default: 0 -- integer; Selection_Conversion

<Turn_to_Poly>.useSoftSelection BooleanClass default: true -- boolean; Use_Soft_Selection

Affects the action of sub-object Move, Rotate, and Scale functions. When these are on, 3ds max applies a spline curve deformation to unselected vertices surrounding the transformed selected sub-object. This provides a magnet-like effect, with a sphere of influence around the transformation. Use this when you want to preserve the soft selection from beneath. For example, if Use Soft Selection is on when you select vertices on an editable mesh, and you apply Turn To Poly with Include Soft Selection on, then the same soft selection will apply to the polymesh vertices. Default=on.

Important: Be aware that when Include Soft Selection is on, bound vertices can turn to meshes.

For more information, see Soft Selection Rollout

<Turn_to_Poly>.selectionLevel Integer default: 0 -- integer; Selection_Level

These options set the sub-object selection level for passing up the rest of the stack.

0: 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.

1: Object. Uses object as the selection level for passing up the rest of the stack.

2: Edge. Uses edge as the sub-object selection level for passing up the rest of the stack.

3: Vertex. Uses vertex as the sub-object selection level for passing up the rest of the stack.

4: 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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


UDynaDeflector - superclass: SpacewarpObject

UDynaDeflector - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID: #(1750561194, 1736524989)

Constructor

...

Properties

<UDynaDeflector>.'time on' Integer default: 0 -- animatable; integer; Time_On

<UDynaDeflector>.'time off' Integer default: 1600000 -- animatable; integer; Time_Off

<UDynaDeflector>.affects Float default: 10000.0 -- animatable; percentage; Reflects; Controller Scaling: (1 : 100.0)

<UDynaDeflector>.bounce Float default: 1.0 -- animatable; float

<UDynaDeflector>.bouncevar Float default: 0.0 -- animatable; percentage; Bounce_Variation; Controller Scaling: (1 : 100.0)

<UDynaDeflector>.chaos Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)

<UDynaDeflector>.friction Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)

<UDynaDeflector>.inheritVelocity Float default: 1.0 -- animatable; float; Velocity_Inheritance

<UDynaDeflector>.radius Float default: 0.0 -- animatable; float; Icon_Size

<UDynaDeflector>.mass Float default: 1.0 -- animatable; float; Particle_Mass

<UDynaDeflector>.'mass units' Integer default: 0 -- radio button number; Particle_Mass_Units

<UDynaDeflector>.number Integer default: 20 -- animatable; integer; Number_of_Particles


UVWUnwrap - superclass: modifier

UVWUnwrap - superclass: modifier; super-superclass:MAXWrapper - 0:0 - classID: #(48180794, 1924812319)

See also

UVWUnwrap interfaces:


Z_Depth - superclass: MAXObject

Z_Depth - superclass: MAXObject; super-superclass:Value - 6:0 - classID: #(12, 0)

Constructor

Z_Depth ...

Properties:

<Z_Depth>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

When on, applies the active antialiasing filter to the rendered element. When off, the rendered element does not use the antialiasing filter. Default=on.

The Filter Enabled column of the elements list shows whether or not the filter is enabled for an element.

You choose the antialiasing filter in the Anti-Aliasing group of the 3ds max Default Scanline A-Buffer rollout.

Disabling antialiasing can improve rendering time, although the rendered element that results might appear jagged.

<Z_Depth>.elementName String default: "Z Depth" -- string

Shows the name of the element. You can change the default name of elements, in the Selected Element Parameters group.

To select an element, click its name in the list. Use CTRL+click to select additional elements, or SHIFT+click to select a contiguous group of additional elements.

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

<Z_Depth>.zMin Float default: 100.0 -- float; Z_Min

The minimum distance to include in the Z-depth rendering. This is a value in 3ds max units. Default=0.0 (cannot be less than zero).

<Z_Depth>.zMax Float default: 300.0 -- float; Z_Max

The maximum distance to include in the Z-depth rendering. This is a value in 3ds max units. Default=100.0.

See also


ZRenderElement - superclass: MAXObject

ZRenderElement - superclass: MAXObject; super-superclass:Value - 6:0 - classID: #(12, 0)

Constructor

ZRenderElement ...

Properties

<ZRenderElement>.enabled BooleanClass default: true -- boolean

Shows whether the element is enabled.

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

When on, applies the active antialiasing filter to the rendered element. When off, the rendered element does not use the antialiasing filter. Default=on.

The Filter Enabled column of the elements list shows whether or not the filter is enabled for an element.

You choose the antialiasing filter in the Anti-Aliasing group of the 3ds max Default Scanline A-Buffer rollout.

Disabling antialiasing can improve rendering time, although the rendered element that results might appear jagged.

<ZRenderElement>.elementName String default: "Z Depth" -- string

Shows the name of the element. You can change the default name of elements, in the Selected Element Parameters group.

To select an element, click its name in the list. Use CTRL+click to select additional elements, or SHIFT+click to select a contiguous group of additional elements.

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

<ZRenderElement>.zMin Float default: 100.0 -- float; Z_Min

The minimum distance to include in the Z-depth rendering. This is a value in 3ds max units. Default=0.0 (cannot be less than zero).

<ZRenderElement>.zMax Float default: 300.0 -- float; Z_Max

The maximum distance to include in the Z-depth rendering. This is a value in 3ds max units. Default=100.0.


Interface: actionMan

Action Manager

All Action Items are macro recorded when executed. This includes main menus items, CUI buttons, keyboard shortcuts and quad menu items.

<boolean>executeAction <integer>tableId <string>persistentId

Returns True if successful and false otherwise.

<boolean>loadKeyboardFile <string>file

Returns True if successful and false otherwise.

<boolean>saveKeyboardFile <string>file

Returns True if successful and false otherwise.

<string>getKeyboardFile()

Returns True if successful and false otherwise.

See also

Action Manager

The Macro Recorder

Defining Macro Scripts

The MAXScript Listener Window

Turning On the Listener Log

Listener Commands


Interface: BoneSys

Bone Creation

Interface: BoneSys

Methods:

<node>createBone <point3>startPos <point3>endPos <point3>zAxis

It returns the new bone node that was created.

<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

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

Core Interfaces

Node Common Properties, Operators, and Methods

Bone Creation

Bone : Helper

Skin : Modifier

Access to the new node bone properties and methods


Interface: browserMgr

This represents the interface to the Browser Manager.

Methods

<Interface>newBrowser <string>rootURL <boolean>showDirectory <boolean>showContent <boolean>showToolbar <boolean>showMenu

This method will create and open a new browser window. It returns an interface to a new browsermgr.

<string>rootURL : The string containing the URL.

<boolean>showDirectory : True to show as a directory, otherwise false.

<boolean>showContent : True to show the content window, otherwise false.

<boolean>showToolbar : True to show the browser toolbar, otherwise false.

<boolean>showMenu: True to show the browser menu, otherwise false.

<integer>numBrowsers()

This method will return the current number of browsers.

<Interface>getBrowser <integer>index

This method allows you to obtain a pointer to a specific browser. It returns an interface to the ith browser.

See also

Asset Browser enhancements

iDrop - drag and drop

Zip-file Script Packages


Interface: cmdPanel

Customize The Order of Rollup Pages

Methods

<integer>GetRollupThreshold()

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.

<void>SetRollupThreshold <integer>threshold

See also

Rollout User-Interface Controls

Rollout User-Interface Controls Types

Rollout User-Interface Controls Common Properties

Rollout User-Interface Controls Common Layout Parameters

Customize The Order of Rollup Pages

Visual MAXScript


Interface: dragAndDrop

iDrop - drag and drop

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.

<void>globalEnableDragAndDrop <boolean>onOff

This method allows you to globally enable or disable the DnD interface.

<boolean>onOff: True to enable, false to disable.

<boolean>isEnabled()

This method returns true if the global DnD interface is enabled, otherwise false.

<boolean>enableDragAndDrop <HWND>window <boolean>onOff

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. Returns true if successful and false otherwise.

<HWND>window : A handle to the window you wish to enable or disable DnD for.

<boolean>onOff: True to enable, False to disable.

<boolean>dropPackage <HWND>window <&point>mousePoint <&string array>files

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 3ds 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. Returns true if the drop was successful, otherwise false.

<HWND>window : A handle to the window. If this is set to NULL, the default 3ds max window is used.

<&point>mousePoint : The point at which to drop.

<&string array>files: A reference to the local copies of the URL strings.

<boolean>downloadPackage <&string array>files <string>directory <boolean>Showprogress

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. Returns true if successful and false otherwise.

<&string array>files : A reference to the local copies of the URL strings.

<string>directory: The directory path string to download to.

<boolean>Showprogress: Displays the progress dialog.

<string>getDownloadDirectory()

This method returns the fully-specified path to the directory in which package drops are downloaded.

<boolean>DownloadUrlToDisk <string>url <string>fileName <integer>flags

This method allows you to download the file referenced by the URL to disk. Returns true if successful and false otherwise.

<string>url : The URL string of the file to download.

<string>fileName : The filename string of the URL to store on disk.

<integer>flags

<node>ImportContextNode()

Returns a pointer to the import context node.

See also

Zip-file Script Packages

iDrop - drag and drop


Interface: HDIKSys

Methods

<void>ikChain <node>startJoint <node>endJoint <boolean>createEndEffector

<boolean>RemoveChain <node>chainNode

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.

See also

HD IK controller chains can be assigned to existing hierarchies


Interface: IKSys

Methods

<node>ikChain <node>startJoint <node>endJoint <string>solver

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.


Interface: manip

Scripted Manipulators

Properties:

.msXYPlane : Interface : Read

.msXZPlane : Interface : Read

.msYZPlane : Interface : Read

<mesh>makeSphere <point3 by value>pos <float>radius <integer>segments

This returns a mesh sphere with the given position, radius, and segments.

<point3 by value>pos: Sets the mesh sphere Position

<float>radius: Specifies the radius of the sphere.

<integer>segments: Sets the number of polygonal divisions for the sphere.

<mesh>makeTorus <point3 by value>pos <float>radius <float>radius2 <integer>segs <integer>sides

Create a torus mesh with the given values.

<point3 by value>pos: Sets the position of the torus.

<float>radius: Sets the distance from the center of the torus to the center of the cross-sectional circle. This is the radius of the torus ring.

<float>radius2: Sets the radius of the cross-sectional circle. The default is 10 units. This value is replaced each time you create a torus.

<integer>segs: Sets the number of radial divisions around the torus. By reducing this number, you can create polygonal rings instead of circular ones.

<integer>sides: Sets the number of sides on the cross-sectional circle of the torus. By reducing this number, you can create prism-like cross sections instead of circular ones.

<mesh>makeBox <point3 by value>pos <float>l <float>w <float>h <integer>lsegs <integer>wsegs <integer>hsegs

Creates a box mesh with the given parameters.

<point3 by value>pos: Sets the position of the Box.

<float>l: Sets the length, width, and height of the Box object. These fields also act as readouts while you drag the sides of the box. Default=0,0,0.

<float>w: Sets the length, width, and height of the Box object. These fields also act as readouts while you drag the sides of the box. Default=0,0,0.

<float>h: Sets the length, width, and height of the Box object. These fields also act as readouts while you drag the sides of the box. Default=0,0,0.

<integer>lsegs: Sets the number of divisions along each axis of the object. Can be set before or after creation. By default, each side of the box is a single segment. When you reset these values, the new values become the default during a session. Default=1,1,1.

Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers. For example, if you're going to bend a box on the Z axis, you might want to set its Height Segments parameter to 4 or more.

<integer>wsegs: Sets the number of divisions along each axis of the object. Can be set before or after creation. By default, each side of the box is a single segment. When you reset these values, the new values become the default during a session. Default=1,1,1.

Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers. For example, if you're going to bend a box on the Z axis, you might want to set its Height Segments parameter to 4 or more.

<integer>hsegs: Sets the number of divisions along each axis of the object. Can be set before or after creation. By default, each side of the box is a single segment. When you reset these values, the new values become the default during a session. Default=1,1,1.

Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers. For example, if you're going to bend a box on the Z axis, you might want to set its Height Segments parameter to 4 or more.

<Interface>makePlaneFromPts <point3 by value>p1 <point3 by value>p2 <point3 by value>p3

<point3 by value>p1

<point3 by value>p2

<point3 by value>p3

<Interface>makePlaneFromNormal <point3 by value>normal <point3 by value>point

Creates a Plane object with the given normal that passes through the given point.

<point3 by value>normal

<point3 by value>point

<Interface>makeGizmoShape()

<Interface>makeCircle <point3 by value>center <float>radius <integer>segments

<point3 by value>center

<float>radius

<integer>segments


Interface: maxOps

maxOps

Properties

.productVersion : enum : Read

productVersion enums: {#productVersionDevel|#productVersionTrial|#productVersionOrdinary|#productVersionEdu|#productVersionNFR}

.licenseBehavior : enum : Read

licenseBehavior enums: {#licenseBehaviorPermanent|#licenseBehaviorExtendable|#licenseBehaviorNonextendable}

.licenseDaysLeft : integer : Read

.trackbar : Interface : Read

Methods

canImportBitmap <string>fileName

Returns true if successful and false otherwise.

displayActiveCameraViewWithMultiPassEffect()

displayActiveCameraViewWithMultiPassEffect - no automatic redraw after invoked

setActiveViewportTransparencyDisplay <integer>transparencyLevel

loadCUIFile <string>fileName

Returns true if successful and false otherwise.

isFeatureLicensed <integer>featureNumber

Returns true if successful and false otherwise.

GetCurRenderElementMgr()

Gets the current render element manager.

GetRenderElementMgr <enum>

{#Production|#Draft}

Gets a specific render element manager.

CollapseNode <node>node <boolean>noWarning

CollapseNodeTo <node>node <index>modIndex <boolean>noWarning

Returns true if successful and false otherwise.

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

Returns true if successful and false otherwise.

<&node array>nodes

<&point3>offset

expandHierarchy:<boolean>

expandHierarchy default value: false

cloneType:<enum>

cloneType enums: {#copy|#instance|#reference}

cloneType default value: #copy

actualNodeList:<node array>

actualNodeList default value: #()

newNodes:<node array>

newNodes default value: #()

setSelectionType <boolean>auto <enum>method

Returns true if successful and false otherwise.

<boolean>auto

method enums: {#window|#crossing|#leftToRight|#rightToLeft}

getNodeByHandle <DWORD>handle

Return a node associated with a given handle.

getTrackBar()

The interface to a trackbar is returned.


Interface: medit

Interface available for Texmap and Mtl Interface_medit.

<maxObject>GetCurMtl()

This method returns a material base pointer for the current material.

<void>SetActiveMtlSlot <index>slot <boolean>forceUpdate

This method allows you to set the active material slot.

<index>slot : The material slot index.

<boolean>forceUpdate: Set this to true to update the slot contents.

<index>GetActiveMtlSlot()

This method returns the index of the active material slot.

<void>PutMtlToMtlEditor <maxObject>mtl <index>slot

This method allows you to put the specified material to the specified material editor slot.

<maxObject>mtl : The material you want to put.

<index>slot: The index of the material slot you wish to put the material into.

<maxObject>GetTopMtlSlot <index>slot

This method returns a pointer to the material base from the specified slot.

<index>slot: The index of the material slot for which you wish to obtain the material.

<boolean>OkMtlForScene <material>mtl

Before assigning material to scene, call this to avoid duplicate names.

<material>mtl: The pointer to the material.

<void>UpdateMtlEditorBrackets()

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

BitmapTex Reload and viewImage


Interface: menuMan

<boolean>loadMenuFile <string>file

This method allows you to load a menu file from disk and automatically update the UI accordingly. Returns true if the menu file was loaded, otherwise false.

<string>file: The path and filename of the menu file to load.

<boolean>saveMenuFile <string>file

This method allows you to save a menu file to disk. Returns true if the menu file was saved, otherwise false.

<string>file: The path and filename of the menu file to save.

<string>getMenuFile()

This method returns the file name of the currently loaded and active menu file.

<void>updateMenuBar()

This method can be called to update 3ds max' main menu bar after adding sub-menu's or menu items.

<boolean>registerMenuContext <integer>contextId

To add items to 3ds 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 3ds max's main menu and Quad menus.

<Interface>findMenu <string>menuName

This method will return a pointer to a menu based on its name. Returns a pointer to the menu or null if the menu wasn't found.

<string>menuName: The name of the menu to return.

<Interface>findQuadMenu <string>menuName

This method will return a pointer to a quad menu based on its name. Returns a pointer to the quad menu or null if the menu wasn't found.

<string>menuName: The name of the menu to return.

<boolean>unRegisterMenu <Interface>menu

This method allows you to remove a menu form the mananger. Returns false if the menu was not registered, true if successfully unregistered.

<Interface>menu: Points to the menu to unregister.

<boolean>unRegisterQuadMenu <Interface>quadMenu

This is like "unregisterMenu" but for quad menus.

<Interface>createMenu <string>name

This creates a new, empty menu with the given name.

<Interface>createQuadMenu <string>name <string>quad1Name <string>quad2Name <string>quad3Name <string>quad4Name

This creates a new, empty quad menu. It contains, 4 empty menus, one for each quad.

<Interface>createSubMenuItem <string>name <Interface>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.

<Interface>createSeparatorItem()

This creates a new menu separator that can be added to a menu.

<Interface>createActionItem <string>macroScriptName <string>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.

<boolean>setViewportRightClickMenu <enum>which <Interface>menu

which enums: {#nonePressed|#shiftPressed|#altPressed|#controlPressed|#shiftAndAltPressed|#shiftAndControlPressed|#controlAndAltPressed|#shiftAndAltAndControlPressed}

This method allows you to set the viewport right-click menu to the specified quad menu. Returns true if it was set successfully.

<enum>which : See the List of Right-Click Contexts above.

<Interface>menu: A pointer to the quad menu you wish to set.

<Interface>getViewportRightClickMenu <enum>which

which enums: {#nonePressed|#shiftPressed|#altPressed|#controlPressed|#shiftAndAltPressed|#shiftAndControlPressed|#controlAndAltPressed|#shiftAndAltAndControlPressed}

This method returns a pointer to the current viewport right-click quad menu.

<enum>which: See the List of Right-Click Contexts..

<Interface>getMainMenuBar()

This method returns a pointer to the main menu bar.

<boolean>setMainMenuBar <Interface>menu

This method allows you to set the main menu bar. Returns true if it was set successfully.

<Interface>menu: A pointer to the menu you wish to set as the main menu bar.

<bool>getShowAllQuads <Interface>quadMenu

This method checks if the "Show All Quads" flag is set for a specific QuadMenu. This method will return true if the flag is set or false if the flag is not set.

<Interface>quadMenu: A pointer to the QuadMenu you wish to check the flag for.

<void>setShowAllQuads <Interface>quadMenu <bool>value

This method sets the "Show All Quads" flag for a specific QuadMenu.

<Interface>quadMenu : A pointer to the QuadMenu you wish to set the flag for.

<bool>value: True to set the flag to on, false to set the flag off.

<string>getQuadMenuName <Interface>quadMenu

This method returns the name given to a specific QuadMenu as a string.

<Interface>quadMenu: A pointer to the QuadMenu for which you wish to retrieve the name.

<void>setQuadMenuName <Interface>quadMenu <string>name

This method allows you to set the name of a specific QuadMenu.

<Interface>quadMenu : A pointer to the QuadMenu for which you wish to set the name.

<string>name: The string containing the name for the QuadMenu.

<integer>numMenus()

Returns the total number of menus in registered with the menu manager.

<Interface>getMenu <index>index

Retrieves the "index"th menu in the menu manager. This is a 1-based index.

<integer>numQuadMenus()

Returns the total number of quad menus registered with the menu manager.

<Interface>getQuadMenu <index>index

Retrieves the "index"th quad menu in the menu manager. This is a 1-based index.

See also

Menu Manager

Interface: quadMenuSettings

Class ImenuManager (in the SDK Help file accompanying this product)


Interface: msZip

<boolean>fileInPackage <string>fileName <&TSTR>extractDir

This method will unload and run a zip package and return the extract_dir. Returns true if the zip package was run, otherwise false. Note: extractDir is In parameter

<string>fileName: The file name of the ZIP script package.

<&TSTR>extractDir: The directory in which the files were extracted.

<boolean>unloadPackage <string>fileName <&TSTR>extractDir <&TSTR>dropFile

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. Returns true if the package was unloaded, otherwise false. Note: extractDir and dropFile are both In parameter

<string>fileName: The file name of the ZIP script package.

<&TSTR>extractDir: The directory in which the files were extracted.

<&TSTR>dropFile: The primary drop file.

See also

Interface: dragAndDrop

Zip-file Script Packages

iDrop - drag and drop


Interface: refhierarchy

This represents an interface to the reference hierarchy.

Interface: refhierarchy

<boolean>IsRefTargetInstanced <maxObject>refTarget

This method can be used to find out if an object is instanced (instanced pipeline). It Checks if the Derived Object is instanced. If it is, the pipeline part below and including that derived object is instanced. In certain circumstances, objects need to find out whether they are instances or not. Some plugins need this functionality in order to properly interpret the size and position of their ModContext bounding box. Returns True if it is an instance, False otherwise. If the argument is NULL, it also returns False.


Interface: NetRender

Methods

<Interface>GetManager()

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.

<netManager>.setCallback #progress | #message | #update | #managerdown | #queuecontrol | #querycontrol <somefunction>

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.

Example:

fn myNetMessage msg = -- NOTE: one string parameter

format "Message: %\n" msg

m.setcallback #message mymessage -- sets the #message callback to use mymessage()

#update myupdate

Called when something has changed, like a job started or finished. Let's you know when you need to make GetUpdate calls, or other refreshing. Requires a function defined with no parameters.

Example:

fn myUpdate =

job.GetUpdate() --example of what you might do

m.setcallback #update myupdate -- sets the #update callback to use myupdate()

#managerdown mymanagerdown

Called when the manager shuts down. Requires a function defined with no parameters.

Example:

fn myManagerDown =

format "Manager is dead\n"

m.setcallback mymanagerdown -- sets the #managerdown callback to use mymanagerdown()

#queuecontrol myqueuecontrol

Called whenever queue control changes. Requires a function defined with no parameters.

Example:

fn myQueueControl =

format "Queue control has changed\n"

m.setcallback #QueueControl myQueueControl --install the "QueueControl" callback

#querycontrol myquerycontrol

Called when you have Queue Control, and another computer wants it, either via the QueueManager, or with the script function <netManager>.QueryControl(). If you want to keep control, set the value <netManager>.WantControl to true, otherwise set it to false. The function must take one arguement, which is the name of the machine requesting control. See the function <netManager>.QueueControl() for more information.

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

<netManager>.GetCallback <#progress | #message | #update | #managerdown | #queuecontrol | #querycontrol>

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

<netManager>.connect #manual <manager name>|<manager IP address> [port:<integer>]

or

<netManager>.connect #automatic <subnet mask> [port:<integer>]

Establishes a connection to the manager, allowing access to job states, server states, editing job settings, etc….It takes 2 arguments and a 3rd optional argument. You can either connect to a manager manually by specifying the manager name or ip address of the manager as a string, or automatically by specifying the subnet mask and optional port number, eg:

m.connect #manual "manager" -- connects to manager of name "manager"

or

m.connect #manual "192.168.0.1" -- connects to manager of IP 192.168.0.1

or

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.

<netManager>.Disconnect()

Disconnects the connection established with <netManager>.connect.

<netManager>.Kill()

Shutsdown the manager. You must have queue control to do this.

<netManager>.QueryControl #wait | #dontwait

This requires either #wait or #dontWait. The function works as follows:

Nobody has queue control: #dontWait returns true, #wait returns true.

Someone has queue control: #dontwait returns false, #wait prompts the current queue controller.

In the last case, the queue controller gets the QueryControl callback, and must indicate if they want control. If that user indicates they want to keep control, then the function returns false, if they will give up control (or the 10 second timeout expires), it returns true. Note that the QueueManager gives a prompt for the user to indicate what they want; in the scripter, you just get the callback and have to use the wantControl value.

Note: Please refer to callback, "#queuecontrol myqueuecontrol", found above in <netManager>.setCallback.

<netManager>.GetControl()

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.

<netManager>.Lock <true | false>

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.

<netManager>.SetUpdates <true | false>

This function's usage resembles 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.

<netManager>.checkoutputvisibility <path>

Takes 1 argument, a pathname defined as a string, ie "c:\\temp". 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.

<netManager>.connected

Returns true if connected to the manager.

<netManager>.netStatus

Returns the status of the manager. Various information about the manager can be gathered through netstatus, see netstatus topic.

<netManager>.wantControl

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

<netManager>.haveControl

True, if you currently have QueueControl.

<netManager>.numJobs

Returns the number of jobs in the queue.

<netManager>.numServers

Returns the number of servers.

<netManager>.numGroups

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.

<netManager>.getjobs [filter:#suspended | #complete | #waiting | #started | #error | #name | #handle | #index] [key:<name> | <handle> | <index>]

The latter three filter types require a corresponding key arguement. If used without a filter, returns an array of all jobs in queue. If no jobs are in the queue, an empty array will be returned.

filter:#suspended: Returns an array of all suspended jobs. Returns an empty array #() if no jobs are suspended

filter:#complete: Returns an array of all completed jobs. Returns an empty array #() if no jobs are complete.

filter:#waiting: Returns an array of jobs that are waiting to be rendered or are being rendered. Will return an empty array #() if no jobs are waiting.

filter:#started: Returns an array of jobs that are actually started and being rendered.

filter:#complete: Returns an array of all completed jobs. Returns an empty array #() if no jobs are complete

filter:#error: Returns an array of all jobs experiencing an error. Returns an empty array #() if no jobs have errors

filter:#name: Pass a name as the Key argument; Returns an array of all jobs with the given name. Returns an empty array #() if the no jobs have that name

filter:#handle: Pass a handle as the Key argument; the job with that handle will be returned (as an array with one element). Returns an empty array #() if the no job has that handle

filter:#index: Pass an integer as the Key argument; the job at that index in the queue will be returned (as an array with one element). Returns an empty array #() if the no job exists at that index

Example:

manager.GetControl() --get queue control

manager.SetUpdates false --the queue is now frozen

jobs = manager.GetJobs()

manager.SetUpdates true --the queue is unfrozen

Note: The GetJobs() function could return incorrect results if the Queue is changed while the job information is downloading. SetUpdates is used to guarantee that GetJobs operates without error.

<netManager>.SetJobOrder <array>

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.

<netManager>.NewJob file:<filename>

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.

Example:

job.newJob file:"file.max" --submitting a file

job.newJob() --submitting the current scene

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.

<job>.GetUpdate()

Updates the information about the selected job. Remember this involves a network interaction, so it's a heavyweight operation

<job>.SendUpdate()

Updates the job in the queue with new job settings. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. Remember this involves a network interaction, so it's a heavyweight operation.

<job>.Submit() Servers:<array>

Submits a new job to be rendered to the queue. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. if no servers are provided, then all servers will be assigned to the job.

<job>.Suspend()

Suspends the selected job. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.

<job>.Resume()

Will cause the job to resume where it left off when it was suspended. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.

<job>.Restart()

Will restart the job from the beginning. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.

<job>.Delete()

Will delete the job from the queue. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.

<job>.AssignServer <server>

Assigns a selected server to the job. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.

<job>.SuspendServer <server>

Removes a server from the selected job. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.

<job>.GetServerInfo <integer>

Gets information about a particular server assigned to the job. Requires a server number, 1 based.

<job>.GetRenderElement <index>

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.

<job>.nonconcurrentDriver

Returns true if the output cannot be rendered one frame at a time (like an .MOV file). READ-ONLY.

<job>.uninterruptibleDriver

Returns true if the render cannot be resumed after it is interrupted or suspended.

For example, you cannot render half of an .AVI file, then finish it later. You need to render the whole thing without interruption. Read-only

<element>.enabled

Returns true if the element is enabled. Can also set it's state.

<element>.filterEnabled

Returns true if filtering is enabled. Can also set it's state.

<element>.atmosphereApplied

Returns true if atmosphere is applied. READ-ONLY

<element>.shadowsApplied

Returns true if shadows are applied. READ-ONLY

<element>.name

Returns the elements name. Name can be changed.

<element>.output

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.

<job>.SetRenderElement <index> <element>

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.

<job>.GetCameras()

Returns an array of cameras in the scene. An empty array #() is returned if no cameras are in the scene.

<job>.GetLog() start:x numLines:y

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.

<job>.GetFrameInfo <integer>

Returns information, as a data structure, about the nth frame. The index is 1 based. The <frame> structure is defined below.

Example:

fr = getframeinfo 4 -- Returns info about the 4th frame. Read-only.

<frame>.state

Returns the state of the frame. The state can be #waiting, #assigned or #complete.

<frame>.index

Returns the actual frame number. Read-only.

<frame>.serverhandle

Returns the serverhandle. Should return undefined when frame hasn't been rendered yet. Read-only.

<frame>.servername

Returns the name of the server that is assigned to that frame. Should return undefined if the frame isn't assigned yet. Read-only.

<frame>.elapsedtime

Returns the time it took for the frame to render. Should return undefined if the frame isn't assigned yet. Read-only.

<job>.GetServerStatusText <server>

Returns any messages from the chosen server assigned to the job. Will return an empty string if no messages from the server. Read-only.

<job>.numServers

Returns the number of servers assigned to the job. Read-only.

<job>.state

Returns the state of the job. This can be #complete, #suspended, #busy or #waiting. Read-only.

<job>.serverPID

This function gives low-level information that is intended for internal-use-only.

<job>.handle

Returns the job's handle. Read-only.

Many of the following values are read-write, but changes you make to these values will not register with the manager until you call <job>.SendUpdate().

Note that SendUpdate requires queue control (obtained via <NetManager>.getControl)

<job>.name

Returns the name of the job. The name can be changed.

<job>.filesize

Returns the job's file size.

<job>.filesizeExtracted

Returns the job's extracted file size. Read-only.

<job>.timeSubmitted

Returns the time at which the job was submitted as a string.

<job>.timeStarted

Returns the time at which the job was started as a string. Returns undefined if job hasn't started. Read-only.

<job>.timeFinished

Returns the time at which the job was finished as a sting. Returns undefined if job hasn't finished. Read-only.

<job>.notifications

Returns true if notifications are on. Can be changed.

<job>.notifyFailure

Returns true if notified of failures. Can be changed.

<job>.notifyProgress

Returns true if notified of progress. Can be changed.

<job>.notifyCompletion

Returns true if notified of progress is on. Can be changed.

<job>.notifyFrameInterval

Returns an interval at which notifications occur. Can be changed.

<job>.fromFrame

Returns the rendering start frame. Can be changed.

<job>.toFrame

Returns the rendering end frame. Can be changed.

<job>.nthFrame

Returns the rendering frame interval. Can be changed.

<job>.outputWidth

Returns the width of the rendered frame. Can be changed.

<job>.outputHeight

Returns the height of the rendered frame. Can be changed.

<job>.numFramesComplete

The number of completed frames for the job. Read-only.

<job>.priority

Returns the job priority.

<job>.videoPost

Returns true if there is a video post sequence. Read-only.

<job>.nonconcurrentDriver

Returns true if the output cannot be rendered one frame at a time (like .MOV). Read-only.

<job>.includeMaps

Returns true if the job was submitted with include maps on. Can be changed.

<job>.uninterruptibleDriver

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.

<job>.skipRenderedFrames

Returns true if skip rendered frames was set to on when job was submitted. Can be changed.

<job>.useAllServers

Returns true if use all servers was set to on when job was submitted. Can be changed

<job>.suspended

Returns true if the job is suspended. Read-only. To suspend the job use <job>.suspend().

<job>.finished

Returns true if the job is finished. Read-only.

<job>.ignoreShare

Returns true if the job was submitted with ignore share on. Can be changed.

<job>.skipOutputTest

Returns true if the job was submitted with skip output test on. Can be changed.

<job>.nonSeqFrames

Returns true if the job was submitted to render non sequential frames. Can be changed.

<job>.combustionJob

Returns false if the job is a max job. Read-only.

<job>.uncompressedFile

Returns false if the job file is compressed. Read-only.

<job>.gammaCorrection

Returns true if the job was submitted with gamma correction on. Can be changed.

<job>.gammaValueIn

Returns a float value of the incomming gamma value. Can be changed.

<job>.gammaValueOut

Returns a float value of the outgoing gamma value. Can be changed.

<job>.renderPixelAspect

Returns a float value of the render pixel aspect ratio. Can be changed.

<job>.renderCamera

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.

<job>.renderElements

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.

<job>.numSceneObjects

Returns the number of objects in the scene as an integer. Read-only.

<job>.numSceneFaces

Returns the number of faces in the scene as an integer. Read-only.

<job>.numSceneLights

Returns the number of lights in the scene as an integer. Read-only.

<job>.sceneStartTime

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.

<job>.sceneEndTime

Returns the scene end time in frames.

<job>.videoColorCheck

Returns true if the job was submitted with videocolorcheck on. Can be changed.

<job>.force2Sided

Returns true if the job was submitted with force 2 sided on. Can be changed.

<job>.renderHiddenObjects

Returns true if the job was submitted with render hidden objects on. Can be changed.

<job>.renderAtmosphericEffects

Returns true if the job was submitted with render render atmospheric effects on. Can be changed.

<job>.superBlack

Returns true if the job was submitted with superblack on. Can be changed.

<job>.serialNumbering

Returns true if nth serial numbering is on this property is accesible through the preferences \ rendering dialog.

<job>.ditherPaletted

Returns true if Dither Paletted was enabled when the job was submitted. Can be changed.

<job>.ditherTrueColor

Returns true if Dither True Color was enabled when the job was submitted. Can be changed.

<job>.renderFields

Returns true if Render Fields was enabled when the job was submitted. Can be changed.

<job>.renderDisplacements

Returns true if displacements was enabled when the job was submitted. Can be changed.

<job>.renderEffects

Returns true if render effects was enabled when the job was submitted. Can be changed.

<job>.fieldOrder

Returns either #odd or #even depending on what the field order was set to when job was submitted. Can be changed.

<job>.numRenderElements

Returns the number of render elements in the scene. Read-only.

<job>.userName

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

<job>.computerName

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

<job>.managerShare

Returns the shared folder as a string where all jobs are stored on the manager.

<job>.frames

Returns a string of frames to render, ie "1,3,5-12". Can be changed.

<job>.frameOutputName

Returns the name and path of the output file. Can be changed

<job>.frameOutputGamma

Returns the output gamma of the rendered frames.

<job>.frameOutputDevice

Returns the device name if a device is specified at render time.

<job>.numFrames

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.

<netManager>.GetServers [filter:#idle | #busy | #absent | #suspended | #error | #group | #job | #handle | #index] [key:<string> | <integer> | <job> ]

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

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

<server>.GetUpdate()

Gets an update on the state of the server. Returns Ok if succesful.

<server>.SendUpdate()

Updates the server with new settings. Must have queuecontrol.

<server>.Delete()

Deletes the server from the manager. Must have queuecontrol.

<server>.ResetPerformance()

Resets the performance metric to 0.0. Must have queuecontrol and must do <server>.sendupdate() to update the server.

<server>.netStatus

Netstatus

<server>.handle

Returns the server's handle. Read-only

<server>.state

Returns the state of the server, this can be #idle, #absent, #busy

<server>.name

Returns the name of the server. Read-only

<server>.totalFrames

Returns the total number of frames rendered by the server. Read-only

<server>.totalTime

Returns the total time that the server has been up. The value returned is in hours.

<server>.performance

Returns the performance index of the server. Read-only

<server>.AttendedPriority

Returns the priority, as an integer, of the server when the user is logged in.

0: high priority

1: low priority

2: idle.

Can be changed.

<server>.UnattendedPriority

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.

<server>.schedule

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.

<server>.jobHandle

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.

<server>.jobFrameIndex

Returns the frame index of the job that the server is working on.

<server>.jobFrameTimeStarted

Returns the time at which the frame being rendered was started.

Working with Groups

<netManager>.SizeofGroup <index>

Returns the number of servers in the nth group.

<netManager>.GetGroupName<index>

Returns the name of the nth group.

<netManager>.CreateGroup <array> <string>

Creates a named group of servers. It takes 2 arguments: an array of servers and a string to define the group name.

<netManager>.DeleteGroup <string>

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

<system>.SpaceOnDisk <index>

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.

<system>.numDroppedPackets

Returns the number of dropped packets.

<system>.numBad

Returns the number of bad packets.

<system>.numTCPRequests

Returns the number of TCP requests

<system>.numUDPRequests

Returns the number of UDP packets

<system>.bootTime

Returns the time at which the system was started.

<system>.memorySize

Returns the amount of memory of the system.

<system>.numProcessors

Returns the number of processors in system machine

<system>.platformID

Returns an integer, a value of 1 indicates win95, a value of 2 indicates WinNT

<system>.majorVersion

Returns an integer. When the platformID indicates a WinNT system, a value of 5 or higher here indicates Win2k.

<system>.minorVersion

Returns an integer. Win98 is indicated by a minor build greater than 0 for win95

<system>.buildNumber

Returns the build number, this only applies to winnt and win2k. Not supported under win95, win98 or win ME.

<system>.CSDVersion

Returns the service pack number of the OS as a string.

<system>.username

Returns the login name of the user logged in on the computer or the login name used by the service.

<system>.tempDir

Returns the tempdir for the system.

<system>.computerName

Returns the name of the computer.

<system>.workdisk

Returns the disk where max is setup.

<system>.Disks

Returns a bitarray of which disks exist (1=A, 2=B, 3=C etc.)

<system>.mac

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

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

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

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 #Message myNetMessage --install the "Message" callback

m.setcallback #Update myUpdate --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

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

Note: Intentionally blank.


Interface: objXRefs

Methods

<maxObject>addNewXRefObject <filename>fname <string>objname <boolean>proxy

<integer>getNumXRefObjects <filename>fname

<maxObject>getXRefObject <filename>fname <index>index

<filename>getFileName <index>index

<boolean>reloadFile <filename>fname

Returns true if successful and false otherwise.

<boolean>isFileUnresolved <filename>fname

Returns true if successful and false otherwise.

<boolean>isFileDisabled <filename>fname

Returns true if successful and false otherwise.

See also

XRefObject : Node

XRefScene Values

XRef Files


Interface: paramWire

Parameter Wiring

This class represents the interface that provides general access to the parameter wiring functions.

<void>start()

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

)

<void>openEditor()

This method will open up the parameter wiring dialog on the selected objects with no track selected in either tree view.

<void>editParams <value>leftParam <value>rightParam

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 3ds max object.

<value>leftParam: The sub-animatable of the left-hand reference target.

<value>rightParam: The sub-animatable of the right-hand reference target.

Note: The subanim index operator can also take number indexes.

<void>editParam <value>param

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 3ds max object.

<value>param: The sub-animatable of the left-hand reference target.

Example:

-- The radius parameter in a sphere node

paramWire.editParam $sphere01.baseObject[#radius]

-- The angle parameter in a bend modifier would be

paramWire.editParam $foo.bend[#angle]

-- The position parameter in node would be

paramWire.editParam $foo[#transform][#position], etc.

<void>editControllers <control>leftController <control>rightController

Opens the parameter wiring editor dialog on the two given existing wire controllers.

<control>leftController: A pointer to the controller for the left-hand wire.

<control>rightController: A pointer to the controller for the right-hand wire.

<void>editController <control>controller

Opens the parameter wiring editor dialog on the given existing wire controller.

<control>controller: A pointer to the controller being edited.

Example:

paramWire.editController $foo.radius.controller

<bool>connect <value>fromParam <value>toParam <string>toExpr

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. Returns true if the connection can be made, otherwise false.

<value>fromParam: The sub-animatable to wire from.

<value>toParam: The sub-animatable to wire to.

<string>toExpr: A string containing the expression on the "to wire".

Example:

paramWire.connect $foo.baseObject[#radius] $baz.bend[#angle] "radius / 2"

<bool>connect2Way <value>leftParam <value>rightParam <string>leftExpr <string>rightExpr

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. Returns true if the connection can be made, otherwise false.

<value>leftParam: The sub-animatable of the left-hand reference target.

<value>rightParam: The sub-animatable of the right-hand reference target.

<string>leftExpr: A string containing the expression for the left-hand target.

<string>rightExpr: A string containing the expression for the right-hand target.

Example:

paramWire.connect2Way $foo.baseObject[#radius] $baz.bend[#angle] \ "angle / 2" "radius * 2"

<bool>disconnect <control>controller

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. Returns true if the disconnect was successful, otherwise false.

<control>controller: A pointer to the wire controller you wish to disconnect.

<bool>disconnect2Way <control>leftController <control>rightController

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. Returns true if the disconnect was successful, otherwise false.

<control>leftController: A pointer to the first wire controller you wish to disconnect.

<control>rightController: A pointer to the second wire controller you wish to disconnect.

See also Class IparamWireMgr, in the SDK Help file accompanying this product.


Interface: pluginManager

Properties

.visible : boolean : Read|Write

Show and hide the plug-in manager.

Methods

<void>loadClass <class>class

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: pluginManager

Plugin_Manager interfaces:


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.

<void>ResetDefaults()

This method will reset the menu settings to their defaults.

<void>SetBorderSize <integer>borderSize

This method allows you to set the menu border size.

<integer>borderSize: The border size in pixels.

<integer>GetBorderSize()

This method returns the menu border size.

<void>SetHorizontalMarginInPoints <integer>horizontalMarginInPoints

This method allows you to set the menu's horizontal margin size.

<integer>horizontalMarginInPoints: The horizontal margin size in points.

<integer>GetHorizontalMarginInPoints()

This method returns the menu's horizontal margin size (in points).

<void>SetVerticalMarginInPoints <integer>verticalMarginInPoints

This method allows you to set the menu's vertical margin size.

<integer>verticalMarginInPoints: The vertical margin size in points.

<integer>GetVerticalMarginInPoints()

This method returns the menu's vertical margin size (in points).

<void>SetItemFontFace <string>szItemFontFace

This method allows you to set the menu item's font typeface.

<string>szItemFontFace: A string containing the typeface name.

<string>GetItemFontFace()

This method returns the name of the menu item's font typeface.

<void>SetTitleFontFace <string>szTitleFontFace

This method allows you to set the menu title's font typeface.

<string>szTitleFontFace: A string containing the typeface name.

<string>GetTitleFontFace()

This method returns the name of the menu title's font typeface.

<void>SetItemFontSize <integer>itemFontSize

This method allows you to set the menu item's font size.

<integer>itemFontSize: The size of the font, in points.

<integer>GetItemFontSize()

This method returns the menu item's font size, in points.

<void>SetTitleFontSize <integer>titleFontSize

This method allows you to set the menu title's font size.

<integer>titleFontSize: The size of the font, in points.

<integer>GetTitleFontSize()

This method returns the menu title's font size, in points.

<void>SetUseUniformItemHeight <boolean>useUniformItemHeight

This method allows you to set the status of a menu item's uniform height flag.

<boolean>useUniformItemHeight: True to set the uniform height flag On, False to set it to Off.

<boolean>GetUseUniformItemHeight()

This method returns true or false if the menu item's uniform height flag is set or not set, respectively.

<void>SetOpacity <float>opacity

This method allows you to set the menu's opacity value.

<float>opacity: The opacity value, ranging from 0.0 – 1.0 where 1 is opaque.

<float>GetOpacity()

This method returns the menu's opacity value.

<void>SetDisplayMethod <integer>displayMethod

This method allows you to set a menu's display method.

<integer>displayMethod: The display method which is one of the following:

0 - displays the menu with transparency, if opacity is < 1.

1 - stretch animate the menu by making it grow in size from its center with transparency, if opacity is < 1.

2 - fade in from invisible to whatever opacity is set to.

<integer>GetDisplayMethod()

This method returns the menu's display method, which is either of the following; DM_NORMAL, DM_STRETCH, DM_FADE, DM_NUM_METHODS

<void>SetAnimatedSteps <integer>animatedSteps

This method allows you to set the menu's number of animated steps for the 'growing' effect.

<integer>animatedSteps: The number of steps.

<integer>GetAnimatedSteps()

This method returns the menu's number of animated steps used for the 'growing' effect.

<void>SetAnimatedStepTime <integer>animatedStepTime

This method allows you to set the menu's animated step time.

<integer>animatedStepTime: The animated step time, in milliseconds.

<integer>GetAnimatedStepTime()

This method returns the menu's animated step time, in milliseconds.

<void>SetSubMenuPauseTime <integer>subMenuPauseTime

This method allows you to set the delay before a submenu is displayed.

<integer>subMenuPauseTime: The delay, in milliseconds.

<integer>GetSubMenuPauseTime()

This method returns the delay before a submenu is displayed, in milliseconds.

<void>SetUseLastExecutedItem <boolean>useLastSelectedItem

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.

<boolean>useLastSelectedItem

<boolean>GetUseLastExecutedItem()

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.

<void>SetRepositionWhenClipped <boolean>repositionWhenClipped

This method allows you to set the flag which controls and determines whether the menu is repositioned when near the edge of the screen.

<boolean>repositionWhenClipped: True to turn repositioning On, false to turn it Off.

<integer>GetRepositionWhenClipped()

This method returns the status of the flag which controls and determines whether the menu is repositioned when near the edge of the screen. Returns true if the flag is on, otherwise false.

<void>SetRemoveRedundantSeparators <boolean>removeRedundantSeparators

This method allows you to set the flag which controls and determines whether the menu should remove redundant separators.

<boolean>removeRedundantSeparators: True to turn the flag On, false to turn it Off.

<integer>GetRemoveRedundantSeparators()

This method returns the status of the flag which controls and determines whether the menu should remove redundant separators. Returns true if the flag is on, otherwise false.

<void>SetFirstQuadDisplayed <integer>firstQuadDisplayed

This method allows you to set the first quad which will be displayed when a quad menu pops up.

<integer>firstQuadDisplayed: The quad index, one of the following; QUAD_ONE, QUAD_TWO, QUAD_THREE, or QUAD_FOUR.

<integer>GetFirstQuadDisplayed()

This method returns the index of the first quad which will be displayed. Returns the quad index, one of the following: QUAD_ONE, QUAD_TWO, QUAD_THREE, or QUAD_FOUR.

<void>SetUseUniformQuadWidth <boolean>useUniformQuadWidth

This method allows you to set whether the quad menu has a uniform width.

<boolean>useUniformQuadWidth: True to set the uniform width, false to set it to non-uniform.

<boolean>GetUseUniformQuadWidth()

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.

<void>SetMirrorQuad <boolean>mirrorQuad

This method allows you to set whether the quad menus are mirrored left to right.

<boolean>mirrorQuad: True to mirror the menus, otherwise false.

<integer>GetMirrorQuad()

This method returns true if the quad menu is mirrored left to right, otherwise false.

<void>SetMoveCursorOnReposition <boolean>moveCursorOnReposition

This method allows you to set whether the cursor moves when the quad menu is repositioned because of clipping the edge of the screen.

<boolean>moveCursorOnReposition: True to move the cursor, otherwise false.

<boolean>GetMoveCursorOnReposition()

This method returns true if the cursor moves when the quad menu is repositioned because of clipping the edge of the screen, otherwise false.

<void>SetReturnCursorAfterReposition <boolean>returnCursorAfterReposition

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.

<boolean>returnCursorAfterReposition: True to set the flag, otherwise False.

<boolean>GetReturnCursorAfterReposition()

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.

<void>SetInitialCursorLocInBox_0to1 <float>initialCursorLocX <float>initialCursorLocY

This method allows you to set the initial location of the cursor in the center quad box.

<float>initialCursorLocX:

<float>initialCursorLocY: The location of the cursor, as a ratio of the box size, between 0.0 and 1.0.

<float>GetInitialCursorLocXInBox_0to1()

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.

<float>GetInitialCursorLocYInBox_0to1()

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.

<void>SetTitleBarBackgroundColor <integer>quad <&RGBA color>color

This method allows you to set the title bar background color for a specific quad. Note: color is In parameter

<integer>quad: The quad (numbered 1 through 4).

<&RGBA color>color: The color to set.

<&RGBA color>GetTitleBarBackgroundColor <integer>quad

This method returns the title bar background color of a specific quad. This method returns the color as a Color.

<integer>quad: The quad (numbered 1 through 4).

<void>SetTitleBarTextColor <integer>quad <&RGBA color>color

This method allows you to set the title bar text color for a specific quad. Note: color is In parameter

<integer>quad: The quad (numbered 1 through 4).

<&RGBA color>color: The color to set.

<&RGBA color>GetTitleBarTextColor <integer>quad

This method returns the title bar text color of a specific quad. This method returns the color as a Color.

<integer>quad: The quad (numbered 1 through 4).

<void>SetItemBackgroundColor <integer>quad <&RGBA color>color

This method allows you to set the item background color for a specific quad. Note: color is In parameter

<integer>quad: The quad (numbered 1 through 4).

<&RGBA color>color: The color to set.

<&RGBA color>GetItemBackgroundColor <integer>quad

This method returns the item background color of a specific quad. This method returns the color as a Color.

<integer>quad: The quad (numbered 1 through 4).

<void>SetItemTextColor <integer>quad <&RGBA color>color

This method allows you to set the item text color for a specific quad. Note: color is In parameter

<integer>quad: The quad (numbered 1 through 4).

<&RGBA color>color: The color to set.

<&RGBA color>GetItemTextColor <integer>quad

This method returns the item text color of a specific quad. This method returns the color as a Color.

<integer>quad: The quad (numbered 1 through 4).

<void>SetLastExecutedItemTextColor <integer>quad <&RGBA color>color

This method allows you to set the last executed item text color for a specific quad. Note: color is In parameter

<integer>quad: The quad (numbered 1 through 4).

<&RGBA color>color: The color to set.

<&RGBA color>GetLastExecutedItemTextColor <integer>quad

This method returns the last executed item text color of a specific quad. This method returns the color as a Color.

<integer>quad: The quad (numbered 1 through 4).

<void>SetHighlightedItemBackgroundColor <integer>quad <&RGBA color>color

This method allows you to set the highlighted item background color for a specific quad. Note: color is In parameter

<integer>quad: The quad (numbered 1 through 4).

<&RGBA color>color: The color to set.

<&RGBA color>GetHighlightedItemBackgroundColor <integer>quad

This method returns the highlighted item background color of a specific quad. This method returns the color as a Color.

<integer>quad: The quad (numbered 1 through 4).

<void>SetHighlightedItemTextColor <integer>quad <&RGBA color>color

This method allows you to set the highlighted item text color for a specific quad. Note: color is In parameter

<integer>quad: The quad (numbered 1 through 4).

<&RGBA color>color: The color to set.

<&RGBA color>GetHighlightedItemTextColor <integer>quad

This method returns the highlighted item text color of a specific quad. This method returns the color as a Color.

<integer>quad: The quad (numbered 1 through 4).

<void>SetBorderColor <integer>quad <&RGBA color>color

This method allows you to set the border color for a specific quad. Note: color is In parameter

<integer>quad: The quad (numbered 1 through 4).

<&RGBA color>color: The color to set.

<&RGBA color>GetBorderColor <integer>quad

This method returns the border color of a specific quad. This method returns the color as a Color.

<integer>quad: The quad (numbered 1 through 4).

<void>SetDisabledShadowColor <integer>quad <&RGBA color>color

This method allows you to set the disabled shadow color for a specific quad. Note: color is In parameter

<integer>quad : The quad (numbered 1 through 4).

<&RGBA color>color: The color to set.

<&RGBA color>GetDisabledShadowColor <integer>quad

This method returns the disabled shadow color of a specific quad. This method returns the color as a Color.

<integer>quad: The quad (numbered 1 through 4).

<void>SetDisabledHighlightColor <integer>quad <&RGBA color>color

This method allows you to set the disabled highlight color for a specific quad. Note: color is In parameter

<integer>quad : The quad (numbered 1 through 4).

<&RGBA color>color: The color to set.

<&RGBA color>GetDisabledHighlightColor <integer>quad

This method returns the disabled highlight color of a specific quad. This method returns the color as a Color.

<integer>quad : The quad (numbered 1 through 4).

See also

Menu Manager

Interface: menuMan

Class ImenuSettings (in the SDK Help file accompanying this product)


Interface: rollup

Note: Intentionally blank.


Interface: SceneExposureControl

Properties

.exposureControl : maxObject : Read|Write|Validated by


Interface: SceneRadiosity

Properties

.radiosity : maxObject : Read|Write|Validated by

Methods

<void>showPanel()

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.

<void>closePanel()

<void>minimizePanel()


Interface: timeSlider

This represents the interface for the time slider.

Methods:

<void>setVisible <boolean>visible

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.

<boolean>visible: True to set the time slider visible, otherwise false.

<boolean>isVisible()

This method returns true if the time slider is visible, otherwise false.

See also Class ItimeSlider, in the SDK Help file accompanying this product.


Interface: trackviews

Properties

.currentTrackView : Interface : Read

.lastUsedTrackViewName : string : Read

Methods

<Interface>getTrackView <fpvalue>name or index

This method will get a trackview based on it's index or name.

<Interface by value array>getAllOpenTrackViews()

Returns an array of trackviews.

<integer>numTrackViews()

Returns the number of trackviews.

<boolean>open <fpvalue>name or index

Open a trackview based on it's index or name.

<boolean>close <fpvalue>name or index

Close a trackview based on it's index or name.

<void>delete <fpvalue>name or index

Delete a trackview based on it's index or name.

<string>getTrackViewName <index>index

Returns the name of the trackview window based on the index.

<boolean>zoomSelected <TSTR>name

Zooms to the selected object's track

<boolean>zoomOn <TSTR>name <maxObject>object <index>subNum

Returns True if successful and false otherwise.

<boolean>setFilter()

setFilter has variable number of arguments. Returns True if successful and false otherwise.

<boolean>clearFilter()

Returns true if successful and false otherwise. clearFilter has variable number of arguments

<fpvalue by value>pickTrackDlg()

pickTrackDlg has variable number of arguments. 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.

<boolean>isOpen <fpvalue>name or index

Returns a boolean value indicating if the specified trackview is open.

<boolean>openLastUsedTrackView()

Opens the current trackview if it has been closed.

<boolean>isCurrent <fpvalue>name or index

Returns a boolean value indicating if the trackview is the last one used or not.

<boolean>setCurrent <fpvalue>name or index

Sets the specified trackview to be the current one. Returns true if successful.

See also

Track View Pick Dialog


Interface: visualMS

This represents an interface to visual MAXScript.

Interface: visualMS

<Interface>createForm()

Creates a VMS instance that is initially hidden. Call the Visual MAXScript form object's .Open method to display it.

Example:

MacroScript Launch_VMS

ButtonText:"Visual MAX Script Editor"

Category:"MAX Script"

internalCategory:"MAX Script"

Tooltip:"Visual MAX Script Editor"

(

vms = visualMS.CreateForm()

vms.Open()

)

<Interface>createFormFromFile <string>fileName


bitmapTex interfaces:

bitmapTex interfaces:

Interface: bitmapTex

Methods

<void>reload()

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.

<void>viewImage()

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.

See also

BitmapTexture : TextureMap

BMP, PNG, JPEG and TGA I/O Interfaces

Material Editor Access

Accessing The Material Editor Active Slot

Material Level Show-in-viewport State

showTextureMap() function


Block_Control interfaces:

Interface: list

Properties

.count : integer : Read

.active : index : Read|Write

Methods:

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method allows you to set the name of an indexed item.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also Class IlistControl, in the SDK Help file accompanying this product.


BMP interfaces:

This represents the interface for the Bitmap IO BMP format.

Interface: ibmpio

Methods

<enum>getType()

getType enums: {#noType|#paletted|#true24}

This method returns the format type, which is one of the enum types. Note: #noType is equivalent to #true24

<void>setType <enum>type

type enums: {#noType|#paletted|#true24}

This method allows you to set the format type. Note: #noType is equivalent to #true24.

<enum>type: The type, which is one of the enum types.

See also Class IBitmapIO_Bmp, in the SDK Help file accompanying this product.


CameraMap interfaces:

Properties

.cameraNode : node : Read|Write

.channel : integer : Read|Write

See also

Camera_Map : Modifier


Flex interfaces:

Flex interfaces:

Interface: flexOps

Methods

<void>paint()

<void>setReference()

<void>reset()

<void>addForce <node>force

<void>removeForce <integer>force

<integer>numberVertices()

<void>selectVertices <bitArray>sel <boolean>update

<bitArray>getSelectedVertices()

<float>getVertexWeight <integer>index

<void>setVertexWeight <int array>indices <float array>values

<void>setEdgeList <bitArray>sel <boolean>update

<bitArray>getEdgeList()

<void>addSpringFromSelection <integer>flag <boolean>addDuplicates

<void>addSpring <integer>indexA <integer>indexB <integer>flag <boolean>addDuplicates

<void>removeAllSprings()

<void>addSpringButton()

<void>removeSpringButton()

<void>optionsButton()

<void>createSimpleSoftButton()

<void>removeSpringByEnd <integer>a

<void>removeSpringByEnds <integer>a <integer>b

<void>removeSpringByIndex <integer>index

<integer>numberSprings()

<integer>getSpringGroup <integer>index

<void>setSpringGroup <integer>index <integer>group

<float>getSpringLength <integer>index

<void>setSpringLength <integer>index <float>length

<integer>getIndex <integer>a <integer>b

See also

PositionSpring interfaces:

Point3Spring interfaces:

SpringPoint3Controller interfaces:

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController interfaces:

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex interfaces:

flexOps const StructDef


float_list interfaces:

This class represents the interface to the list controller.

Interface: list

Properties

.count : integer : Read

.active : index : Read|Write

Methods

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method allows you to set the name of an indexed item.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also Class IlistControl, in the SDK Help file accompanying this product.


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

<void>reactTo <maxObject>object

The default influence value depends on the time the reaction was created. This is a time variant function so it will use the MAXScript time context instead of requiring a Time value as an argument.

<maxObject>object: The object to react to. This can either be a controller or a node.

<boolean>create name:<string>

Create a new reaction and give it a name. The default influence value depends on the time the reaction was created. This is a time variant function. It will also use the name supplied if there is one, but a name is not necessary. The default value of name is: "scriptCreated". Returns true if successful and false otherwise.

Note: All index parameters below are 1-based.

<boolean>delete <index>index

Returns true if successful and false otherwise.

<integer>getCount()

Returns the reaction count.

<void>select <index>index

<index>getSelected()

<boolean>setStateToCurrent <index>index

This is a Time Variant function. Sets the reaction state to the current state at the given MAXScript time. Returns true if successful and false otherwise.

<boolean>setFloatState <index>index <float>state

Set the reaction state to the value passed in. The function you use depends on the type of reactor controller it is. Returns true if successful and false otherwise.

<boolean>setVectorState <index>index <point3>state

Set the reaction state to the value passed in. The function you use depends on the type of reactor controller it is. Returns true if successful and false otherwise.

<boolean>setRotationState <index>index <quat>state

Set the reaction state to the value passed in. The function you use depends on the type of reactor controller it is. Returns true if successful and false otherwise.

<boolean>setValueToCurrent <index>index

This is a Time Variant function. Sets the reaction value to value of the ReactTo object at the given MAXScript time. Returns true if successful and false otherwise.

<boolean>setValueAsFloat <index>index <float>value

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. Returns true if successful and false otherwise.

<boolean>setValueAsVector <index>index <point3>value

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. Returns true if successful and false otherwise.

<boolean>setValueAsQuat <index>index <quat>value

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. Returns true if successful and false otherwise.

<boolean>setInfluence <index>index <float>influence

Sets the influence for the specified reaction. Returns true if successful and false otherwise.

<boolean>setStrength <index>index <float>strength

Sets the strength for the specified reaction. Returns true if successful and false otherwise.

<boolean>setFalloff <index>index <float>influence

Sets the falloff for the specified reaction.

<void>setName <index>index <string>name

Set the name of the reaction specified by the index.

<string>getName <index>index

Returns the reaction name.

<float>getInfluence <index>index

Returns the reaction influence.

<float>getStrength <index>index

Returns the reaction strength.

<float>getFalloff <index>index

Returns the reaction falloff.

<enum>getType()

getType enums: { #floatReaction | #positionalReaction | #rotationalReaction | #scaleReaction }

Returns the type of object you are reacting to.

<fpvalue by value>getState <index>index

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.

<fpvalue by value>getValue <index>index

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 and allows you to set the slave animation controller.

<maxObject>getWireParent <index>index

This method returns a pointer to the i-th dependent parameter parent.

<index>index: The index you wish to retrieve.

<integer>getWireSubnum <index>index

This method returns the i-th dependent parameter subanim num in the animatable.

<index>index: The index of the subanim.

<control>getCoController <index>index

This method returns a pointer to the i-th CoController.

<index>index: The index of the controller.

<string>getExprText <index>index

This method returns the expression string of the i-th wire parameter.

<index>index: The index of the parameter.

<void>setExprText <index>index <string>text

This method allows you to set the expression string of the i-th wire parameter.

<index>index : The index of the parameter

<string>text: The expression you wish to set.

See also Class IbaseWireControl, in the SDK Help file accompanying this product.


FloatList interfaces:

This class represents the interface to the list controller.

Properties

.count : integer : Read

.active : index : Read|Write

Methods

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method allows you to set the name of an indexed item.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also Class IlistControl, in the SDK Help file accompanying this product.


FloatReactor interfaces:

FloatReactor interfaces:

Interface: reactions

Properties

.editStateMode : boolean : Read|Write

.useCurve : boolean : Read|Write

Methods

<void>reactTo <maxObject>object

<boolean>create name:<string>

name default value: "scriptCreated"}

<boolean>delete <index>index

<integer>getCount()

<void>select <index>index

<index>getSelected()

<boolean>setStateToCurrent <index>index

<boolean>setFloatState <index>index <float>state

<boolean>setVectorState <index>index <point3>state

<boolean>setRotationState <index>index <quat>state

<boolean>setValueToCurrent <index>index

<boolean>setValueAsFloat <index>index <float>value

<boolean>setValueAsVector <index>index <point3>value

<boolean>setValueAsQuat <index>index <quat>value

<boolean>setInfluence <index>index <float>influence

<boolean>setStrength <index>index <float>strength

<boolean>setFalloff <index>index <float>influence

<void>setName <index>index <string>name

<string>getName <index>index

<float>getInfluence <index>index

<float>getStrength <index>index

<float>getFalloff <index>index

<enum>getType()

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}

<fpvalue by value>getState <index>index

<fpvalue by value>getValue <index>index

Actions:


HSDS_Modifier interfaces:

HSDS_Modifier interfaces:

Interface: hsdsOps

Methods

<void>subdivide()

<void>deletePolygon()

<void>hide()

<void>showAll()

<void>createNamedSelection <string>name

<void>activateNamedSelection <string>name

<void>addDetail <float>length <float>angle

<void>removeDetail <float>length <float>angle

Actions:


HSDSObject interfaces:

HSDSObject interfaces:

Interface: hsdsOps

Methods

<void>subdivide()

<void>deletePolygon()

<void>hide()

<void>showAll()

<void>createNamedSelection <string>name

<void>activateNamedSelection <string>name

<void>addDetail <float>length <float>angle

<void>removeDetail <float>length <float>angle

Actions:


IKChainControl interfaces:

IKChainControl interfaces:

Interface: Action

Methods

<float>snap() -- Action Interface

<float>ikSnap() -- Action Interface

<float>fkSnap() -- Action Interface

Actions:

Category: IK_Chain_Actions; Action: IK_Chain_Snap_Action; Shortcut: -- none defined --

Category: IK_Chain_Actions; Action: IK_Chain_IK_Snap; Shortcut: -- none defined --

Category: IK_Chain_Actions; Action: IK_Chain_FK_Snap; Shortcut: -- none defined –


imageMotionBlur interfaces:

imageMotionBlur interfaces:

Interface: ImageMotionBlur

Properties:

methods:

Actions:


JPEG interfaces:

This represents the interface for the Bitmap IO JPG format.

Interface: ijpegio

Methods

<integer>getQuality()

This method returns the quality level of the output image.

<void>setQuality <integer>quality

This method allows you to set the quality level of the output image.

<integer>quality: The quality level.

<integer>getSmoothing()

This method returns the smoothing level of the output image.

<void>setSmoothing <integer>smoothing

This method allows you set the smoothing level of the output image.

<integer>smoothing: The smoothing level.

See also Class IBitmapIO_Jpeg, in the SDK Help file accompanying this product.


Link interfaces:

Link interfaces:

Interface: constraints

Properties:

methods:

<node>getTarget <index>index

<boolean>setTarget <node>target <index>index

<float>getFrameNo <index>index <time>time

<boolean>setFrameNo <integer>frameNo <index>index <time>time

<integer>getNumTargets()

<boolean>appendTarget <node>target <time>time

<void>DeleteTarget <integer>targetNumber

Actions:


Link_Constraint interfaces:

Link_Constraint interfaces:

Interface: constraints

Methods:

<node>getTarget <index>index

<boolean>setTarget <node>target <index>index

<float>getFrameNo <index>index <time>time

<boolean>setFrameNo <integer>frameNo <index>index <time>time

<integer>getNumTargets()

<boolean>appendTarget <node>target <time>time

<void>DeleteTarget <integer>targetNumber


LookAt_Constraint interfaces:

This class is an interface to the LookAt Constraint rotation controller.

Interface: constraints

Methods

<node>getTarget <index>index

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.

<index>index: The node number in the Look-At target list to be obtained.

<boolean>setTarget <node>target <index>index

Sets one of the Look-At nodes that the Look-At constraint controller targets, by targetNumber. If targetNumber is greater than the number of targets in the current list, it returns false. In this case use the function AppendTarget. Returns true if successful; False otherwise.

<node>target: Points to the node to follow.

<index>index: The node number in the Look-At target list to be set.

<float>getWeight <index>index <time>time

Gets the weight of one of the Look-At nodes that the Look-At constraint controller targets, specified by targetNumber, and time t.

<index>index : The node number in the Look-At target list whose weight is to be obtained.

<time>time: The time at which the weight is to be obtained. The weights are animatable.

<boolean>setWeight <float>weight <index>index <time>time

Sets the weight of one of the Look-At nodes that the Look-At constraint controller follows, specified by targetNumber, and time t. Returns true if there is more than one Look-At targets in the list and you are trying to set weight, False otherwise.

<float>weight : The weight to set.

<index>index : The node number in the Look-At target list whose weight is to be set.

<time>time: The time at which the weight is to be set. The weights are animatable.

<integer>getNumTargets()

Returns the number of nodes in the list of nodes to look at.

<void>appendWeightedTarget <node>target <float>weight

Appends the current Look-At target list by one and appends the current Look-At target weightlist by one.

<node>target : The node that is to be appended to the current Look-At target list.

<float>weight: This is the weight that is to be assigned to the newly appended Look-At target. The default weight is 50.0.

<boolean>appendTarget <node>target

Appends the current Look-At target list by one and appends the current Look-At target weightlist by one.

<node>target: The node that is to be appended to the current Look-At target list.

<boolean>getRelative()

Gets the relative/absolute mode corresponding to the "Keep Initial Offset" checkbox in the UI.

<boolean>getUpnodeWorld()

Returns true if the "World" checkbox is on; False if off.

<boolean>getStoUpAxisFlip()

Returns true if the "selected" axis flip checkbox is on; False if off.

<boolean>getTargetAxisFlip()

Returns true if the "source" axis flip checkbox is on; False if off.

<boolean>getSetOrient()

Returns true if the orientation flag is set, False if off.

<boolean>getTargetAxis()

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. This method returns one of the following values:

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.

<boolean>getUpNodeAxis()

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. This method returns one of the following values:

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.

<boolean>getStoUPAxis()

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. This method returns one of the following values:

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.

<void>setRelative <boolean>rel

This method allows you to set the "relative" flag.

<boolean>rel: True to set the relative flag, otherwise False.

<void>setUpnodeWorld <boolean>upnode

This method allows you to set the "World" flag.

<boolean>upnode: True to set the world flag, otherwise false.

<void>setTargetAxisFlip <boolean>staxflip

This method allows you to set the "source" flip axis flag.

<boolean>staxflip: True to set the source flip axis flag, otherwise false.

<void>setStoUPAxisFlip <boolean>ssuaflip

This method allows you to set the "selected" axis flip flag.

<boolean>ssuaflip: True to set the selected axis flip flag, otherwise false.

<void>setSetOrient <boolean>ssorient

This method allows you to set the orientation flag.

<boolean>ssorient: True to set the orientation flag, otherwise false.

<void>setResetOrient()

Resets to zero the amount of orientation offset, effected through the "Set Orientation" feature.

<void>setTargetAxis <integer>staxis

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.

<integer>staxis:

0: if TargetAxis coincides with the X axis of the source object.

1: if TargetAxis coincides with the Y axis of the source object.

2: if TargetAxis coincides with the Z axis of the source object

<void>setUpNodeAxis <integer>sunaxis

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.

<integer>sunaxis:

0: if the upnode X axis coincides with a specified source axis.

1: if the upnode Y axis coincides with a specified source axis.

2: if the upnode Z axis coincides with a specified source axis.

<void>setStoUPAxis <integer>ssuaxis

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.

<integer>ssuaxis:

0: if the source X axis coincides with a specified upnode axis.

1: if the source Y axis coincides with a specified upnode axis.

2: if the source Z axis coincides with a specified upnode axis.

<boolean>GetVLisAbs()

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. Returns true if the ViewLine length is absolute, false otherwise.

<void>SetVLisAbs <boolean>rel

Sets the relative/absolute mode corresponding to the "Keep ViewLine Length Absolute" checkbox in the UI.

<boolean>rel: True if "Keep ViewLine Length Absolute" is active (checked), false otherwise.

<void>deleteTarget <integer>targetNumber

This method allows you to delete a specified target.

<integer>targetNumber: The zero based node number in the list of nodes the controller looks at.

See also Class IlookAtConstRotation, in the SDK Help file accompanying this product.


Motion_Blur interfaces:

Motion_Blur interfaces:

Interface: ImageMotionBlur

Properties

Methods


Orientation_Constraint interfaces:

Orientation_Constraint interfaces:

Interface: constraints

Methods

<node>getTarget <index>index

<boolean>setTarget <node>target <index>index

<float>getWeight <index>index <time>time

<boolean>setWeight <float>weight <index>index <time>time

<integer>getNumTargets()

<integer>getlw()

<void>appendWeightedTarget <node>target <float>weight

<void>deleteNode <integer>targetNumber


path interfaces:

This class represents the interface to the Path Position Controller.

Interface: constraints

Methods

<integer>getNumTargets()

Returns the number of nodes in the path list.

<node>getTarget <index>index

Gets one of the path nodes that the path controller follows, specified by targetNumber.

<index>index: The node number in the path list to be obtained.

<boolean>setTarget <node>target <index>index <float>getWeight <index>index <time>time

Gets the weight of one of the path nodes that the path controller follows, specified by targetNumber, and time. If the targetNumber is not relevant then 0.0f is returned.

<index>index : The node number in the path list whose weight is to be obtained.

<boolean>setWeight <float>weight <index>index <time>time

Sets the weight of one of the path nodes that the path controller follows, specified by targetNumber. Returns true if there is more than one path in the list and you are trying to set weight, false otherwise.

<float>weight : The weight to assign.

<index>index : The node number in the path list whose weight is to be set.

<void>appendWeightedTarget <node>target <float>weight

Appends the current path list by one and appends the current weight list by one.

<node>target : The node that is to be appended to the current path list.

<float>weight: The weight to be assigned to the newly appended path.

<void>setFollow <boolean>isSetFollow

This method allows you to set the follow flag.

<boolean>isSetFollow: True for on, false for off.

<boolean>getFollow()

This method returns the state of the follow flag. True if on; False if off.

<void>setBankAmount <float>bankAmount

Sets the bank amount parameter. Bank and tracking are scaled in the UI.

<float>bankAmount: The bank amount.

<float>getBankAmount()

Returns the bank amount setting. See the remarks in SetBankAmount() above.

<void>SetBank <boolean>isSetBank

Sets the bank parameter to on or off.

<boolean>isSetBank: True for on; False for off.

<boolean>getBank()

Returns the on/off state of the bank parameter. True if on; False if off.

<void>setTracking <float>tracking

Sets the smoothness parameter.

<float>tracking: The smoothness setting.

<float>getTracking()

Returns the smoothness setting. See remarks in SetTracking() above.

<void>setAllowFlip <boolean>allowFlip

Sets the state of the 'Allow Upside Down' parameter.

<boolean>allowFlip: True for on; False for off.

<boolean>getAllowFlip()

Returns the state of the 'Allow Upside Down' parameter. Returns True for on; False for off.

<void>setConstVel <boolean>constVel

Sets the state of the 'Constant Velocity' parameter.

<boolean>constVel: True for on; False for off.

<boolean>getConstVel()

Returns the state of the 'Constant Velocity' parameter. Returns True for on; False for off.

<void>setFlip <boolean>Flip

Sets the state of the 'Flip' parameter.

<boolean>Flip: True for on; False for off.

<boolean>getFlip()

Returns the state of the 'Flip' parameter. Returns True for on; False for off.

<void>setAxis <integer>isSetFollow

Set the state of the axis parameter.

<integer>isSetFollow: The axis setting:

0: X axis.

1: Y axis.

2: Z axis.

<integer>getAxis()

Returns the axis setting as one of the following values:

0: X axis.

1: Y axis.

2: Z axis.

<void>setLoop <boolean>Loop

This method allows you to set the state of the loop flag.

<boolean>Loop: True for on; False for off.

<boolean>getLoop()

Returns the state of the loop flag; True for on; False for off.

<void>setRelative <boolean>relative

This method allows you to set the state of the relative/absolute flag.

<boolean>relative: True to set to relative; False to set to absolute.

<boolean>getRelative()

Returns the state of the relative/absolute flag; True if relative is on; False is off (i.e. absolute).

<void>deleteTarget <integer>targetNumber

This method allows you to delete a specified target. Returns True if successful, otherwise False.

<integer>targetNumber: The node number in the orientation target list to delete.

See also Class IpathPosition, in the SDK Help file accompanying this product.


Path_Constraint interfaces:

This class represents the interface to the Path Position Controller.

Interface: constraints

Methods

<integer>getNumTargets <node>getTarget <index>index

Returns one of the path nodes that the path controller follows, specified by targetNumber.

<index>index: The node number in the path list to be obtained.

<boolean>setTarget <node>target <index>index <float>getWeight <index>index <time>time

Gets the weight of one of the path nodes that the path controller follows, specified by targetNumber, and time. If the targetNumber is not relevant then 0.0f is returned.

<index>index: The node number in the path list whose weight is to be obtained.

<boolean>setWeight <float>weight <index>index <time>time

Sets the weight of one of the path nodes that the path controller follows, specified by targetNumber. Returns True if there is more than one path in the list and you are trying to set weight, False otherwise.

<index>index : The node number in the path list whose weight is to be set.

<float>weight: The weight to assign.

<void>appendWeightedTarget <node>target <float>weight

Appends the current path list by one and appends the current weight list by one.

<node>target: The node that is to be appended to the current path list.

<float>weight: The weight to be assigned to the newly appended path. Default: 50.0

<void>setFollow <boolean>isSetFollow

This method allows you to set the follow flag.

<boolean>isSetFollow: True for on, False for off.

<boolean>getFollow()

This method returns the state of the follow flag; True if on, False if off.

<void>setBankAmount <float>bankAmount

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.

<float>bankAmount: The bank amount.

<float>getBankAmount()

Returns the bank amount setting. See the remarks in SetBankAmount() above.

<void>SetBank <boolean>isSetBank

Sets the bank parameter to on or off.

<boolean>isSetBank: True for on; False for off.

<boolean>getBank()

Returns the on/off state of the bank parameter. True if on; False if off.

<void>setTracking <float>tracking

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.

<float>tracking: The smoothness setting.

<float>getTracking()

Returns the smoothness setting. See remarks in SetTracking() above.

<void>setAllowFlip <boolean>allowFlip

Sets the state of the 'Allow Upside Down' parameter.

<boolean>allowFlip: True for on; False for off.

<boolean>getAllowFlip()

Returns the state of the 'Allow Upside Down' parameter. True for on; False for off.

<void>setConstVel <boolean>constVel

Sets the state of the 'Constant Velocity' parameter.

<boolean>constVel: True for on; False for off.

<boolean>getConstVel()

Returns the state of the 'Constant Velocity' parameter. Returns True for on; False for off.

<void>setFlip <boolean>Flip

Sets the state of the 'Flip' parameter.

<boolean>Flip: True for on; False for off.

<boolean>getFlip()

Returns the state of the 'Flip' parameter; True for on, False for off.

<void>setAxis <integer>isSetFollow

Set the state of the axis parameter.

<integer>isSetFollow: The axis setting. One of the following values:

0: X axis.

1: Y axis.

2: Z axis.

<integer>getAxis()

Returns the axis setting as one of the following values:

0: X axis.

1: Y axis.

2: Z axis.

<void>setLoop <boolean>Loop

This method allows you to set the state of the loop flag.

<boolean>Loop: True for on; False for off.

<boolean>getLoop()

Returns the state of the loop flag; True for on, False for off.

<void>setRelative <boolean>relative

This method allows you to set the state of the relative/absolute flag.

<boolean>relative: True to set to relative; False to set to absolute.

<boolean>getRelative()

Returns the state of the relative/absolute flag; True if relative is on; False is off (i.e. absolute).

<void>deleteTarget <integer>targetNumber

This method allows you to delete a specified target. Returns True if successful, otherwise False.

<integer>targetNumber: The node number in the orientation target list to delete.

See also Class IpathPosition, in the SDK Help file accompanying this product.


Plugin_Manager interfaces:

Plugin_Manager interfaces:

Interface: PluginMgrAction

Methods:

<float>show() -- Action Interface

Actions:

Category: Plugin_Manager; Action: Plugin_Manager; Shortcut: -- none defined –

See also

Plug-In Manager

Interface: pluginManager


Portable_Network_Graphics interfaces:

This represents the interface for the Bitmap IO PNG format.

Interface: ipngio

Methods:

<enum>getType()

getType enums: {#paletted|#true24|#true48|#gray8|#gray16}

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.

<void>setType <enum>type

enums: {#paletted|#true24|#true48|#gray8|#gray16}

This method allows you to set the bitmap type.

<enum>type: One of the following: BMM_PALETTED, BMM_True_24, BMM_True_48, BMM_GRAY_8, or BMM_GRAY_16.

<boolean>getAlpha()

This method returns True if the alpha flag is set, otherwise False.

<void>setAlpha <boolean>useAlpha

This method allows you to set the alpha flag.

<boolean>useAlpha: True to set the alpha flag, otherwise False.

<boolean>getInterlaced()

This method returns True if the interlaced flag is set, otherwise False.

<void>setInterlaced <boolean>Interlaced

This method allows you to set the interlaced flag.

<boolean>Interlaced: True to set the interlaced flag, otherwise False.

See Also In the SDK Help file accompanying this product

Class IBitmapIO_Png


point3_list interfaces:

This class represents the interface to the list controller.

Interface: list

Properties:

.count : integer : Read

.active : index : Read|Write

Methods

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method allows you to set the name of an indexed item.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also Class IlistControl, in the SDK Help file accompanying this product.


Point3_Reactor interfaces:

Point3_Reactor interfaces:

Interface: reactions

Properties

.editStateMode : boolean : Read|Write

.useCurve : boolean : Read|Write

Methods

<void>reactTo <maxObject>object

<boolean>create name:<string>

name default value: "scriptCreated"}

<boolean>delete <index>index

<integer>getCount()

<void>select <index>index

<index>getSelected()

<boolean>setStateToCurrent <index>index

<boolean>setFloatState <index>index <float>state

<boolean>setVectorState <index>index <point3>state

<boolean>setRotationState <index>index <quat>state

<boolean>setValueToCurrent <index>index

<boolean>setValueAsFloat <index>index <float>value

<boolean>setValueAsVector <index>index <point3>value

<boolean>setValueAsQuat <index>index <quat>value

<boolean>setInfluence <index>index <float>influence

<boolean>setStrength <index>index <float>strength

<boolean>setFalloff <index>index <float>influence

<void>setName <index>index <string>name

<string>getName <index>index

<float>getInfluence <index>index

<float>getStrength <index>index

<float>getFalloff <index>index

<enum>getType()

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}

<fpvalue by value>getState <index>index

<fpvalue by value>getValue <index>index

Actions:


Point3_Wire interfaces:

Interface: wireController

Properties:

.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).

.isMaster : boolean : Read

This property will return True if the wire is a master predicate, otherwise it will return False.

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

<maxObject>getWireParent <index>index

This method returns a pointer to the i-th dependent parameter parent.

<index>index: The index you wish to retrieve.

<integer>getWireSubnum <index>index

This method returns the i-th dependent parameter subanim num in the animatable.

<index>index: The index of the subanim.

<control>getCoController <index>index

This method returns a pointer to the i-th CoController.

<index>index: The index of the controller.

<string>getExprText <index>index

This method returns the expression string of the i-th wire parameter.

<index>index: The index of the parameter.

<void>setExprText <index>index <string>text

This method allows you to set the expression string of the i-th wire parameter.

<index>index : The index of the parameter

<string>text: The expression you wish to set.

See also In the SDK Help file accompanying this product

Class IBaseWireControl


Point3List interfaces:

This class represents the interface to the list controller.

Interface: list

Properties

.count : integer : Read

.active : index : Read|Write

Methods

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method allows you to set the name of an indexed item.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also In the SDK Help file accompanying this product

Class IListControl


Point3Reactor interfaces:

Point3Reactor interfaces:

Interface: reactions

Properties

.editStateMode : boolean : Read|Write

.useCurve : boolean : Read|Write

Methods

<void>reactTo <maxObject>object

<boolean>create name:<string>

name default value: "scriptCreated"}

<boolean>delete <index>index

<integer>getCount()

<void>select <index>index

<index>getSelected()

<boolean>setStateToCurrent <index>index

<boolean>setFloatState <index>index <float>state

<boolean>setVectorState <index>index <point3>state

<boolean>setRotationState <index>index <quat>state

<boolean>setValueToCurrent <index>index

<boolean>setValueAsFloat <index>index <float>value

<boolean>setValueAsVector <index>index <point3>value

<boolean>setValueAsQuat <index>index <quat>value

<boolean>setInfluence <index>index <float>influence

<boolean>setStrength <index>index <float>strength

<boolean>setFalloff <index>index <float>influence

<void>setName <index>index <string>name

<string>getName <index>index

<float>getInfluence <index>index

<float>getStrength <index>index

<float>getFalloff <index>index

<enum>getType()

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}

<fpvalue by value>getState <index>index

<fpvalue by value>getValue <index>index

Actions:


Point3Spring interfaces:

Interface: Spring

Methods

<float>getMass()

Returns the mass.

<void>setMass <float>mass

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.

<float>getDrag()

Returns the drag.

<void>setDrag <float>drag

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.

<float>getTension <index>springIndex

Gets the tension for the spring corresponding to the index.

<void>setTension <index>springIndex <float>tension

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

<float>getDampening <index>springIndex

Gets the dampening for the spring corresponding to the index.

<void>setDampening <index>springIndex <float>dampening

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.

<boolean>addSpring <node>node

Adds the node to the spring list. Returns true if successful, false otherwise

<integer>getSpringCount()

Returns the number of springs in the spring system.

<void>removeSpringByIndex <index>springIndex

Removes the spring corresponding to the index.

<void>removeSpring <node>node

Removes the spring if the node is in the spring list.

See also

PositionSpring interfaces:

Point3Spring interfaces:

SpringPoint3Controller interfaces:

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController interfaces:

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex interfaces:

flexOps const StructDef


Point_Cache interfaces:

This represents the interface to the PointCache Modifier.

Interface: pointCache

Methods

<void>record()

This method will press the Record button in the rollup interface.

<void>setCache()

This method will press the Set Cache button in the rollup interface.

<void>enableMods()

This method will press the Enable Modifiers Below button in the rollup interface.

<void>disableMods()

This method will press the Disable Modifiers Below button in the rollup interface.

See also

Point Cache Modifier

Point_Cache - superclass: modifier

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

Point_CacheSpacewarpModifier interfaces:

Class IpointCache, in the SDK Help file accompanying this product


Point_CacheSpacewarpModifier interfaces:

This represents the interface to the PointCache Modifier.

Interface: pointCacheWSM

Methods

<void>record()

This method will press the Record button in the rollup interface.

<void>setCache()

This method will press the Set Cache button in the rollup interface.

<void>enableMods()

This method will press the Enable Modifiers Below button in the rollup interface.

<void>disableMods()

This method will press the Disable Modifiers Below button in the rollup interface.

See also

Point Cache Modifier

Point_Cache interfaces:

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

Class IPointCacheWSM (in the SDK Help file accompanying this product)


PointCache interfaces:

This represents the interface to the PointCache Modifier.

Interface: pointCache

Methods

<void>record()

This method will press the Record button in the rollup interface.

<void>setCache()

This method will press the Set Cache button in the rollup interface.

<void>enableMods()

This method will press the Enable Modifiers Below button in the rollup interface.

<void>disableMods()

This method will press the Disable Modifiers Below button in the rollup interface.

See also

Point Cache Modifier

Point_Cache - superclass: modifier

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

Point_CacheSpacewarpModifier interfaces:

Class IpointCache (in the SDK Help file accompanying this product)


PointCacheWSM interfaces:

This represents the interface to the PointCache Modifier.

Interface: pointCacheWSM

Methods

<void>record()

This method will press the Record button in the rollup interface.

<void>setCache()

This method will press the Set Cache button in the rollup interface.

<void>enableMods()

This method will press the Enable Modifiers Below button in the rollup interface.

<void>disableMods()

This method will press the Disable Modifiers Below button in the rollup interface.

See also

Point Cache Modifier

Point_Cache - superclass: modifier

Point_Cache interfaces:

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

Class IPointCacheWSM (in the SDK Help file accompanying this product)


Position_Constraint interfaces:

Position_Constraint interfaces:

This class represents the interface to the Position Constraint.

Interface: constraints

Methods

<integer>getNumTargets()

Returns the number of target nodes in the position target list.

<node>getTarget <index>index

Gets one of the position nodes that the position constraint controller targets, specified by targetNumber.

<index>index: The node number in the position target list to be obtained.

<boolean>setTarget <node>target <index>index

<float>getWeight <index>index <time>time

Gets the weight of one of the position nodes that the position constraint controller targets, specified by targetNumber, and time. Returns the position target weight if the targetNumber is relevant, 0.0f otherwise.

<index>index : The node number in the position target list to set.

<boolean>setWeight <float>weight <index>index <time>time

Sets the weight of one of the position nodes that the position constraint controller follows, specified by targetNumber, and time. Returns True if there is more than one position target in the list and you are trying to set weight, False otherwise.

<index>index: The node number in the position target list whose weight is to be set.

<float>weight: The weight to set.

<boolean>appendTarget <node>target <float>weight

Appends the current position target list by one.

<node>target : The node that is to be appended to the current position target list.

<float>weight: This is the weight that is to be assigned to the newly appended position target. The default weight is 50.0.

<void>deleteTarget <integer>targetNumber

This method allows you to delete a specified target. Returns True if successful, otherwise False.

<integer>targetNumber: The node number in the position target list to delete.

See also Class IposConstPosition, in the SDK Help file accompanying this product.


position_list interfaces:

This class represents the interface to the list controller.

Interface: list

Properties

.count : integer : Read

.active : index : Read|Write

Methods

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also Class IlistControl, in the SDK Help file accompanying this product.


Position_Reactor interfaces:

Position_Reactor interfaces:

Interface: reactions

Properties

.editStateMode : boolean : Read|Write

.useCurve : boolean : Read|Write

Methods

<void>reactTo <maxObject>object

<boolean>create name:<string>

name default value: "scriptCreated"}

<boolean>delete <index>index

<integer>getCount()

<void>select <index>index

<index>getSelected()

<boolean>setStateToCurrent <index>index

<boolean>setFloatState <index>index <float>state

<boolean>setVectorState <index>index <point3>state

<boolean>setRotationState <index>index <quat>state

<boolean>setValueToCurrent <index>index

<boolean>setValueAsFloat <index>index <float>value

<boolean>setValueAsVector <index>index <point3>value

<boolean>setValueAsQuat <index>index <quat>value

<boolean>setInfluence <index>index <float>influence

<boolean>setStrength <index>index <float>strength

<boolean>setFalloff <index>index <float>influence

<void>setName <index>index <string>name

<string>getName <index>index

<float>getInfluence <index>index

<float>getStrength <index>index

<float>getFalloff <index>index

<enum>getType()

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}

<fpvalue by value>getState <index>index

<fpvalue by value>getValue <index>index

Actions:


Position_Wire interfaces:

This represents the interface for individual wire controllers.

Interface: wireController

Properties:

.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).

.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, and allows you to set the slave animation controller.

<maxObject>getWireParent <index>index

This method returns a pointer to the i-th dependent parameter parent.

<index>index: The index you wish to retrieve.

<integer>getWireSubnum <index>index

This method returns the i-th dependent parameter subanim num in the animatable.

<index>index: The index of the subanim.

<control>getCoController <index>index

This method returns a pointer to the i-th CoController.

<index>index: The index of the controller.

<string>getExprText <index>index

This method returns the expression string of the i-th wire parameter.

<index>index: The index of the parameter.

<void>setExprText <index>index <string>text

This method allows you to set the expression string of the i-th wire parameter.

<index>index : The index of the parameter

<string>text: The expression you wish to set.

See also Class IbaseWireControl, in the SDK Help file accompanying this product.


PositionList interfaces:

This class represents the interface to the list controller.

Interface: list

Properties

.count : integer : Read

.active : index : Read|Write

Methods

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method allows you to set the name of an indexed item.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also Class IlistControl, in the SDK Help file accompanying this product.


PositionReactor interfaces:

PositionReactor interfaces:

Interface: reactions

Properties

.editStateMode : boolean : Read|Write

.useCurve : boolean : Read|Write

Methods

<void>reactTo <maxObject>object

<boolean>create name:<string>

name default value: "scriptCreated"}

<boolean>delete <index>index

<integer>getCount()

<void>select <index>index

<index>getSelected()

<boolean>setStateToCurrent <index>index

<boolean>setFloatState <index>index <float>state

<boolean>setVectorState <index>index <point3>state

<boolean>setRotationState <index>index <quat>state

<boolean>setValueToCurrent <index>index

<boolean>setValueAsFloat <index>index <float>value

<boolean>setValueAsVector <index>index <point3>value

<boolean>setValueAsQuat <index>index <quat>value

<boolean>setInfluence <index>index <float>influence

<boolean>setStrength <index>index <float>strength

<boolean>setFalloff <index>index <float>influence

<void>setName <index>index <string>name

<string>getName <index>index

<float>getInfluence <index>index

<float>getStrength <index>index

<float>getFalloff <index>index

<enum>getType()

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}

<fpvalue by value>getState <index>index

<fpvalue by value>getValue <index>index

Actions:


PositionSpring interfaces:

Interface: Spring

Methods

<float>getMass()

Returns the mass.

<void>setMass <float>mass

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.

<float>getDrag()

Returns the drag.

<void>setDrag <float>drag

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.

<float>getTension <index>springIndex

Gets the tension for the spring corresponding to the index.

<void>setTension <index>springIndex <float>tension

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

<float>getDampening <index>springIndex

Gets the dampening for the spring corresponding to the index.

<void>setDampening <index>springIndex <float>dampening

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.

<boolean>addSpring <node>node

Adds the node to the spring list. Returns true if successful, false otherwise

<integer>getSpringCount()

Returns the number of springs in the spring system.

<void>removeSpringByIndex <index>springIndex

Removes the spring corresponding to the index.

<void>removeSpring <node>node

Removes the spring if the node is in the spring list.

See also

PositionSpring interfaces:

Point3Spring interfaces:

SpringPoint3Controller interfaces:

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController interfaces:

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex interfaces:

flexOps const StructDef


radiusManip interfaces:

Interface: Manip

Properties

.mouseState : enum : Read

mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods

<void>clearGizmos()

This must be called at the beginning of the "updateGizmos" handler in order to clear the current gizmo cache.

<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by value>selColor

This creates a gizmo from a mesh (or geometry in 3ds max lingo). The mesh can be any arbitrary 3ds 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.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>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 be 0, or one or more of these values. If you want more than one flag to apply, then you add the values together.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

marker enums: {point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

The position is a point in 3d space, or 2d screen space.

<point3 by value>position : The position is a point in 3d space, or 2d screen space.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>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.

<ray by value>getLocalViewRay <point2 by value>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.

<void>updateGizmos <time>t <&TSTR>toolTip


RenderElementMgr interfaces:

Interface: RenderElementMgr

<boolean>AddRenderElement <maxObject>element

Adds a specific element. Returns True if Successful, False otherwise

<boolean>RemoveRenderElement <maxObject>element

Removes a specific element. Returns true is successful and false otherwise.

<void>RemoveAllRenderElements()

Removes all elements in the list.

<integer>NumRenderElements()

Returns number of elements in list

<maxObject>GetRenderElement <integer>index

Returns a specific element, index is 0 based.

<void>SetElementsActive <boolean>active

Sets a boolean indicating elements are active, ie. will be created during a render.

<boolean>GetElementsActive()

Gets a boolean indicating elements are active, ie. will be created during a render.

<void>SetDisplayElements <boolean>display

Sets boolean indicating elements will be displayed after they are created.

<boolean>GetDisplayElements()

Gets boolean indicating elements will be displayed after they are created.

<void>SetCombustionOutputEnabled <boolean>enabled

Enables or disables output to combustion .cws file.

<boolean>GetCombustionOutputEnabled()

Gets boolean indicating enabled output to combustion .cws file.

<void>SetCombustionOutputPath <string>pathname

Sets the filename of the .cws file.

<string>GetCombustionOutputPath()

Gets the filename of the .cws file.

Example:

-- set a list of render elements.

elementlist = #(specular,diffuse,self_illumination,reflection,refraction,shadowrenderelement,atmosphere,blend,z_depth,alpha,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


rotation_list interfaces:

This represents the interface to the list controller.

Interface: list

Properties

.count : integer : Read

.active : index : Read|Write

Methods

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method allows you to set the name of an indexed item.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also Class IlistControl, in the SDK Help file accompanying this product.


Rotation_Reactor interfaces:

Rotation_Reactor interfaces:

Interface: reactions

Properties

.editStateMode : boolean : Read|Write

.useCurve : boolean : Read|Write

Methods

<void>reactTo <maxObject>object

<boolean>create name:<string>

name default value: "scriptCreated"}

<boolean>delete <index>index

<integer>getCount()

<void>select <index>index

<index>getSelected()

<boolean>setStateToCurrent <index>index

<boolean>setFloatState <index>index <float>state

<boolean>setVectorState <index>index <point3>state

<boolean>setRotationState <index>index <quat>state

<boolean>setValueToCurrent <index>index

<boolean>setValueAsFloat <index>index <float>value

<boolean>setValueAsVector <index>index <point3>value

<boolean>setValueAsQuat <index>index <quat>value

<boolean>setInfluence <index>index <float>influence

<boolean>setStrength <index>index <float>strength

<boolean>setFalloff <index>index <float>influence

<void>setName <index>index <string>name

<string>getName <index>index

<float>getInfluence <index>index

<float>getStrength <index>index

<float>getFalloff <index>index

<enum>getType()

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}

<fpvalue by value>getState <index>index

<fpvalue by value>getValue <index>index

Actions:


Rotation_Wire interfaces:

This represents the interface for individual wire controllers.

Interface: wireController

Properties:

.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).

.isMaster : boolean : Read

This property will return True if the wire is a master predicate, otherwise it will return False.

.isSlave : boolean : Read

This method will return True if the wire is a slave predicate, otherwise it will return False.

.isTwoWay : boolean : Read

This method will return True if the wire is a two-way predicate, otherwise it will return False.

.slaveAnimation : control : Read|Write

This method returns a pointer to the slave animation controller, and allows you to set the slave animation controller.

<maxObject>getWireParent <index>index

This method returns a pointer to the i-th dependent parameter parent.

<index>index: The index you wish to retrieve.

<integer>getWireSubnum <index>index

This method returns the i-th dependent parameter subanim num in the animatable.

<index>index: The index of the subanim.

<control>getCoController <index>index

This method returns a pointer to the i-th CoController.

<index>index: The index of the controller.

<string>getExprText <index>index

This method returns the expression string of the i-th wire parameter.

<index>index: The index of the parameter.

<void>setExprText <index>index <string>text

This method allows you to set the expression string of the i-th wire parameter.

<index>index : The index of the parameter

<string>text: The expression you wish to set.

See also Class IbaseWireControl, in the SDK Help file accompanying this product.


RotationList interfaces:

This class represents the interface to the list controller.

Interface: list

Properties

.count : integer : Read

.active : index : Read|Write

Methods

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method allows you to set the name of an indexed item.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also Class IlistControl, in the SDK Help file accompanying this product.


RotationReactor interfaces:

RotationReactor interfaces:

Interface: reactions

Properties

.editStateMode : boolean : Read|Write

.useCurve : boolean : Read|Write

Methods

<void>reactTo <maxObject>object

<boolean>create name:<string>

name default value: "scriptCreated"}

<boolean>delete <index>index

<integer>getCount()

<void>select <index>index

<index>getSelected()

<boolean>setStateToCurrent <index>index

<boolean>setFloatState <index>index <float>state

<boolean>setVectorState <index>index <point3>state

<boolean>setRotationState <index>index <quat>state

<boolean>setValueToCurrent <index>index

<boolean>setValueAsFloat <index>index <float>value

<boolean>setValueAsVector <index>index <point3>value

<boolean>setValueAsQuat <index>index <quat>value

<boolean>setInfluence <index>index <float>influence

<boolean>setStrength <index>index <float>strength

<boolean>setFalloff <index>index <float>influence

<void>setName <index>index <string>name

<string>getName <index>index

<float>getInfluence <index>index

<float>getStrength <index>index

<float>getFalloff <index>index

<enum>getType()

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}

<fpvalue by value>getState <index>index

<fpvalue by value>getValue <index>index

Actions:


scale_list interfaces:

This class represents the interface to the list controller.

Interface: list

Properties

.count : integer : Read

.active : index : Read|Write

Methods

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method allows you to set the name of an indexed item.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also Class IlistControl, in the SDK Help file accompanying this product.


Scale_Reactor interfaces:

Scale_Reactor interfaces:

Interface: reactions

Properties

.editStateMode : boolean : Read|Write

.useCurve : boolean : Read|Write

Methods

<void>reactTo <maxObject>object

<boolean>create name:<string>

name default value: "scriptCreated"}

<boolean>delete <index>index

<integer>getCount()

<void>select <index>index

<index>getSelected()

<boolean>setStateToCurrent <index>index

<boolean>setFloatState <index>index <float>state

<boolean>setVectorState <index>index <point3>state

<boolean>setRotationState <index>index <quat>state

<boolean>setValueToCurrent <index>index

<boolean>setValueAsFloat <index>index <float>value

<boolean>setValueAsVector <index>index <point3>value

<boolean>setValueAsQuat <index>index <quat>value

<boolean>setInfluence <index>index <float>influence

<boolean>setStrength <index>index <float>strength

<boolean>setFalloff <index>index <float>influence

<void>setName <index>index <string>name

<string>getName <index>index

<float>getInfluence <index>index

<float>getStrength <index>index

<float>getFalloff <index>index

<enum>getType()

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}

<fpvalue by value>getState <index>index

<fpvalue by value>getValue <index>index

Actions:


Scale_Wire interfaces:

This represents the interface for individual wire controllers.

Interface: wireController

Properties:

.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).

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

<maxObject>getWireParent <index>index

This method returns a pointer to the i-th dependent parameter parent.

<index>index: The index you wish to retrieve.

<integer>getWireSubnum <index>index

This method returns the i-th dependent parameter subanim num in the animatable.

<index>index: The index of the subanim.

<control>getCoController <index>index

This method returns a pointer to the i-th CoController.

<index>index: The index of the controller.

<string>getExprText <index>index

This method returns the expression string of the i-th wire parameter.

<index>index: The index of the parameter.

<void>setExprText <index>index <string>text

This method allows you to set the expression string of the i-th wire parameter.

<index>index : The index of the parameter

<string>text: The expression you wish to set.

See also Class IbaseWireControl, in the SDK Help file accompanying this product.


ScaleList interfaces:

This class represents the interface to the list controller.

Interface: list

Properties

.count : integer : Read

.active : index : Read|Write

Methods

<integer>getCount()

This method returns the number of items that appear in the List controllers list box.

<void>setActive <index>listIndex

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.

<index>listIndex: The index of the item to set as the active item.

<integer>getActive()

This method returns the index of the currently active item.

<void>delete <index>listIndex

This method allows you to delete the indexed sub controller from the list.

<index>listIndex: The index of the item to delete from the list.

<void>cut <index>listIndex

This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

<index>listIndex: The index of the item you wish to cut.

<void>paste <index>listIndex

This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.

<index>listIndex: The index of the slot to paste into.

<TSTR by value>getName <index>listIndex

This method returns the class name of the indexed sub-controller if a user defined name doesn't exist.

<index>listIndex: The index of the item for which to get the name.

<void>setName <index>listIndex <string>name

This method allows you to set the name of an indexed item.

<index>listIndex : The index of the item.

<string>name: The name to set it to.

See also Class IlistControl, in the SDK Help file accompanying this product.


ScaleReactor interfaces:

ScaleReactor interfaces:

Interface: reactions

Properties

.editStateMode : boolean : Read|Write

.useCurve : boolean : Read|Write

Methods

<void>reactTo <maxObject>object

<boolean>create name:<string>

name default value: "scriptCreated"}

<boolean>delete <index>index

<integer>getCount()

<void>select <index>index

<index>getSelected()

<boolean>setStateToCurrent <index>index

<boolean>setFloatState <index>index <float>state

<boolean>setVectorState <index>index <point3>state

<boolean>setRotationState <index>index <quat>state

<boolean>setValueToCurrent <index>index

<boolean>setValueAsFloat <index>index <float>value

<boolean>setValueAsVector <index>index <point3>value

<boolean>setValueAsQuat <index>index <quat>value

<boolean>setInfluence <index>index <float>influence

<boolean>setStrength <index>index <float>strength

<boolean>setFalloff <index>index <float>influence

<void>setName <index>index <string>name

<string>getName <index>index

<float>getInfluence <index>index

<float>getStrength <index>index

<float>getFalloff <index>index

<enum>getType()

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}

<fpvalue by value>getState <index>index

<fpvalue by value>getValue <index>index

Actions:


sliderManipulator interfaces:

Interface: Manip

Scripted Manipulators

Properties

.mouseState : enum : Read

mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods

<void>clearGizmos()

This must be called at the beginning of the "updateGizmos" handler in order to clear the current gizmo cache.

<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by value>selColor

This creates a gizmo from a mesh (or geometry in 3ds max lingo). The mesh can be any arbitrary 3ds 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.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>selColor

This creates a gizmo from a shape object. The gizmoShape can be created using functions from the "manip" package, described below.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

marker enums: {point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by addGizmoShape.

<point3 by value>position : The position is a point in 3d space, or 2d screen space.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>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.

<ray by value>getLocalViewRay <point2 by value>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.

<void>updateGizmos <time>t <&TSTR>toolTip

See also

Scripted Manipulators

Interface: manip

radiusManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper

sliderManipulator interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:


SpringPoint3Controller interfaces:

Interface: Spring

Methods

<float>getMass()

Returns the mass.

<void>setMass <float>mass

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.

<float>getDrag()

Returns the drag.

<void>setDrag <float>drag

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.

<float>getTension <index>springIndex

Gets the tension for the spring corresponding to the index.

<void>setTension <index>springIndex <float>tension

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

<float>getDampening <index>springIndex

Gets the dampening for the spring corresponding to the index.

<void>setDampening <index>springIndex <float>dampening

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.

<boolean>addSpring <node>node

Adds the node to the spring list. Returns true if successful, false otherwise

<integer>getSpringCount()

Returns the number of springs in the spring system.

<void>removeSpringByIndex <index>springIndex

Removes the spring corresponding to the index.

<void>removeSpring <node>node

Removes the spring if the node is in the spring list.

See also

PositionSpring interfaces:

Point3Spring interfaces:

SpringPoint3Controller interfaces:

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController interfaces:

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex interfaces:

flexOps const StructDef


SpringPositionController interfaces:

Interface: Spring

Methods

<float>getMass()

Returns the mass.

<void>setMass <float>mass

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.

<float>getDrag()

Returns the drag.

<void>setDrag <float>drag

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.

<float>getTension <index>springIndex

Gets the tension for the spring corresponding to the index.

<void>setTension <index>springIndex <float>tension

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

<float>getDampening <index>springIndex

Gets the dampening for the spring corresponding to the index.

<void>setDampening <index>springIndex <float>dampening

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.

<boolean>addSpring <node>node

Adds the node to the spring list. Returns true if successful, false otherwise

<integer>getSpringCount()

Returns the number of springs in the spring system.

<void>removeSpringByIndex <index>springIndex

Removes the spring corresponding to the index.

<void>removeSpring <node>node

Removes the spring if the node is in the spring list.

See also

PositionSpring interfaces:

Point3Spring interfaces:

SpringPoint3Controller interfaces:

SpringPoint3Controller - superclass: Point3Controller

SpringPositionController interfaces:

SpringPositionController - superclass: PositionController

Flex : Modifier

Flex interfaces:

flexOps const StructDef


Targa interfaces:

This class represents the interface for the Bitmap IO TGA format.

Interface: itgaio

Methods

<integer>getColorDepth()

This method returns the color depth, which would be 16, 24, or 32.

<void>setColorDepth <integer>colorDepth

This method allows you to set the color depth.

<integer>colorDepth: The color depth, being either 16, 24, or 32.

<boolean>getCompressed()

This method returns True if the compression flag is set, otherwise False.

<void>setCompressed <boolean>compression

This method allows you to set the compression flag.

<boolean>compression: True to set the compression flag, otherwise False.

<boolean>getAlphaSplit()

This method returns True if the alpha split flag is set, otherwise False.

<void>setAlphaSplit <boolean>alphaSplit

This method allows you to set the alpha split flag.

<boolean>alphaSplit: True to set the alpha split flag, otherwise False.

<boolean>getPreMultAlpha()

This method returns True if the premultiplied alpha flag is set, otherwise False.

<void>setPreMultAlpha <boolean>preMultAlpha

This method allows you to set the premultiplied alpha flag.

<boolean>preMultAlpha: True to set the premultiplied alpha flag, otherwise False.

See also Class IBitmapIO_Tga, in the SDK Help file accompanying this product.


Unwrap_UVW interfaces:

This class represents the interface to the UVW Unwrap Modifier.

Interface: unwrap

Methods

<void>planarMap()

This method will press the Planar Map button in the rollup interface.

<void>save()

This method will press the Save button in the rollup interface.

<void>load()

This method will press the Load button in the rollup interface.

<void>reset()

This method will press the Reset button in the rollup interface.

<void>edit()

This method will press the Edit button in the rollup interface.

<void>setMapChannel <integer>mapChannel

This method will set the Map Channel field value in the rollup.

<integer>mapChannel: The Map Channel you want to set to.

<integer>getMapChannel()

This method will return the Map Channel field in the rollup.

<void>setProjectionType <integer>mapChannel

This method will set the mapping type.

<integer>mapChannel: The mapping type:

1: for X aligned

2: for Y aligned

3: for Z aligned

4: for normal aligned.

<integer>getProjectionType()

This method will return the mapping type; 1 for X aligned, 2 for Y aligned, 3 for Z aligned, 4 for normal aligned.

<void>setVC <boolean>vertexColor

This method will set the Vertex Color Channel radio button in the rollup interface.

<boolean>vertexColor : True to enable; False to disable.

<boolean>getVC()

This method returns the current state of the Vertex Color Channel radio button in the rollup interface.

<void>move()

This method will press the Move button in the edit floater.

<void>moveh()

This method will press the Move Horizontal button in the edit floater.

<void>movev()

This method will press the Move Vertical button in the edit floater.

<void>rotate()

This method will press the Rotate button in the edit floater.

<void>scale()

This method will press the Scale button in the edit floater.

<void>scaleh()

This method will press the Scale Horizontal button in the edit floater.

<void>scalev()

This method will press the Scale Vertical button in the edit floater.

<void>mirrorH()

This method will press the Mirror Horizontal button in the edit floater.

<void>mirrorV()

This method will press the Mirror Vertical button in the edit floater.

<void>expandSelection()

This method will press the Expand Selection button in the edit floater.

<void>contractSelection()

This method will press the Contract Selection button in the edit floater.

<void>setFalloffType <integer>falloffType

This method will set the Falloff type.

<integer>falloffType: The falloff type; 1 for linear, 2 for sinual, 3 for fast, and 4 for slow.

<integer>getFalloffType()

This method will return the falloff type; 1 for linear, 2 for sinual, 3 for fast, and 4 for slow.

<void>setFalloffSpace <integer>falloffSpace

This method will set the space you want the falloff to be computed in.

<integer>falloffSpace: The falloff space; 1 for XY, the local space of the object, 2 for UV, the UVW space of the object.

<integer>getFalloffSpace()

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.

<void>setFalloffDist <float>falloffDist

This method will set the falloff distance in the edit floater.

<float>falloffDist: The falloff distance.

<float>getFalloffDist()

This method will return the falloff distance.

<void>breakSelected()

This method will press the Break Selected button in the edit floater.

<void>weld()

This method will press the Target Weld button in the edit floater.

<void>weldSelected()

This method will press the Weld Selected button in the edit floater.

<void>updateMap()

This method will press the Update Map button in the edit floater.

<void>DisplayMap <boolean>displayMap

This method sets the state of the Display Map button in the edit floater

<boolean>displayMap

True to toggle the Display Map button on; False to toggle it off.

<boolean>IsMapDisplayed()

This method returns the state of the Display Map button in the edit floater. True if it's on; False if it's off.

<void>setUVSpace <integer>UVSpace

This method sets the space that you want to view the texture vertices in.

<integer>UVSpace: The texture space; 1 for UV, 2 for VW, 3 for UW.

<integer>getUVSpace()

This method returns the space that the texture vertices are viewed in; 1 for UV, 2 for VW, 3 for UW.

<void>options()

This method will press the Options button in the edit floater.

<void>lock()

This method will toggle the Lock Selected Vertices button in the edit floater.

<void>hide()

This method will press the Hide button in the edit floater.

<void>unhide()

This method will press the Unhide button in the edit floater.

<void>freeze()

This method will press the Freeze button in the edit floater.

<void>unfreeze()

This method will press the Unfreeze button in the edit floater.

<void>filterselected()

This method will press the Filter Selected Faces button in the edit floater.

<void>pan()

This method will press the Pan button in the edit floater.

<void>zoom()

This method will press the Zoom button in the edit floater.

<void>zoomRegion()

This method will press the Zoom Region button in the edit floater.

<void>fit()

This method will press the Fit button in the edit floater.

<void>fitselected()

This method will press the Fit Selected button in the edit floater.

<void>snap()

This method will press the Snap button in the edit floater.

<integer>getCurrentMap()

This method returns the index into the map drop down list of the current map in the view of the edit floater.

<void>setCurrentMap <integer>map

This method sets the currently displayed map to the specified map index.

<integer>map: The index of the map in the drop down list to display.

<integer>numberMaps()

This method returns the number of maps in the map drop down list.

<point3>getLineColor()

This method returns the color of the lines used to connect the texture vertices edges as a Point3 pointer.

<void>setLineColor <point3>color

This method sets the line color of the texture vertices.

<point3>color: The color as a Point3.

<point3>getSelectionColor()

This method returns the texture vertices selection color as Point3.

<void>setSelectionColor <point3>color

This method sets the color of selected texture vertices.

<point3>color: The color as a Point3.

<integer>getRenderWidth()

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.

<void>setRenderWidth <integer>width

This method sets the width of the bitmap used to render to for display.

<integer>width: The width in pixels.

<integer>getRenderHeight()

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.

<void>setRenderHeight <integer>height

This method sets the width of the bitmap used to render to for display.

<integer>height: The height in pixels.

<boolean>getUseBitmapRes()

This method returns the state of the Use Bitmap Resolution, if false the bitmaps are rendered using the RenderWidth/Height values.

<void>setUseBitmapRes <boolean>useRes

This method sets the state of the Use Bitmap Resolution value. If it is false the bitmaps are rendered using the RenderWidth/Height values.

<boolean>useRes: True to toggle on; False to toggle off.

<float>getWeldThreshold()

This method returns the weld threshold.

<void>setWeldThreshold <float>height

This method sets the threshold values for welds.

<float>height: The welding threshold/

<boolean>getConstantUpdate()

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.

<void>setConstantUpdate <boolean>update

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.

<boolean>update: True to toggle on; False to toggle off.

<boolean>getShowSelectedVertices()

This method returns whether the selected texture vertices are also displayed in the view port.

<void>setShowSelectedVertices <boolean>show

This method sets whether the selected texture vertices are also displayed in the view port.

<boolean>show: True to toggle on; False to toggle off.

<boolean>getMidPixelSnap()

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.

<void>setMidPixelSnap <boolean>snap

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.

<boolean>snap: True to toggle on; False to toggle off.

<integer>getMatID()

This method returns the current material id index filter.

<void>setMatID <integer>matid

This method sets the material drop list to the index supplied.

<integer>matid: The material ID index to set.

<integer>numberMatIDs()

This method returns the number of material ids in the material id filter drop down.

<bitArray>getSelectedVertices()

This method returns the current selected texture vertices in the edit floater as a bit array.

<void>selectVertices <bitArray>selection

This method selects texture vertices in the edit floater dialog.

<bitArray>selection: The selection set as a bit array.

<boolean>isVertexSelected <integer>index

This method returns whether a texture vertex is selected.

<integer>index: The index of the vertex to check.

<void>MoveSelectedVertices <point3>offset

This method moves the selected texture vertices by the offset.

<point3>offset: The offset by which you want to move the vertices.

<void>RotateSelectedVerticesCenter <float>angle

This method rotates the selected vertices around their center point.

<float>angle: The angle in radians that you want to rotate the selection by.

<void>RotateSelectedVertices <float>angle <point3>axis

This method rotates the selected vertices around a specified point.

<float>angle: The angle in radians that you want to rotate the selection by.

<point3>axis: The axis that you want to rotate the selected vertices by. This is in the space of the window.

<void>ScaleSelectedVerticesCenter <float>scale <integer>dir

This method scales the selected points around their center.

<float>scale: The amount that you want to scale by

<integer>dir: The direction; 1 for uniform scaling, 2 for X, and 3 for Y.

<void>ScaleSelectedVertices <float>scale <integer>dir <point3>axis

This method scales the selected points around a specified point.

<float>scale: The amount that you want to scale by

<integer>dir: The direction; 1 for uniform scaling, 2 for X, and 3 for Y.

<point3>axis: The axis that you want to scale the selected vertices by. This is in the space of the window.

<point3>GetVertexPosition <time>time <integer>index

This method returns the position of the vertex.

<time>time: The time at which you want to get the vertex.

<integer>index: The index of the vertex.

<integer>numberVertices()

This method returns the number of texture vertices

<void>moveX <float>p

This method sets the selected vertices x values in absolute coordinates.

<float>p: The absolute position along the x axis

<void>moveY <float>p

This method sets the selected vertices y values in absolute coordinates.

<float>p: The absolute position along the y axis

<void>moveZ <float>p

This method sets the selected vertices z values in absolute coordinates.

<float>p: The absolute position along the s axis

<bitArray>getSelectedPolygons()

This method returns the selected polygons in the view port as a bit array.

<void>selectPolygons <bitArray>selection

This method selects the polygons in the view ports.

<bitArray>selection: The polygons you wish to select.

<boolean>isPolygonSelected <integer>index

This method returns whether a polygon is selected or not.

<integer>index: The index of the polygon to check.

<integer>numberPolygons()

This method returns the number of polygons in the object.

<void>detachEdgeVertices()

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.

<void>flipHorizontal()

This method will press the Flip Horizontal button in the edit floater.

<void>flipVertical()

This method will press the Flip Vertical button in the edit floater.

<boolean>getLockAspect()

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. Returns True if locked; False if unlocked.

<void>setLockAspect <boolean>aspect

This method sets the Lock Aspect Ratio value

<boolean>aspect: True to lock; False to unlock.

<float>getMapScale()

This method returns the scaling factor when the user applies a planar map. The smaller the value the more planar map is scaled down.

<void>setMapScale <float>scale

This method sets the scaling factor when the user applies a planar map. The smaller the value the more planar map is scaled down

<float>scale: The scaling factor for planar map.

<void>getSelectionFromFace()

This method takes the current polygon selection and uses it to select the texture vertices that are associated with it.

<void>forceUpdate <boolean>update

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.

<boolean>update: This determines whether the mapping is reset on topology change. True to update, otherwise False.

<void>zoomToGizmo <boolean>all

This method zooms the selected or all the viewports to zoom to the current planar map gizmo.

<boolean>all: This determines whether the active or all the viewports get zoomed. True to zoom all viewports, False to view the active viewport.

<void>setVertexPosition <time>time <integer>index <point3>pos

This method sets the position of a UVW vertex at a specific time.

<time>time : The time at what you want to set the position.

<integer>index : The index of the vertex.

<point3>pos: The position of the vertex in UVW space.

<void>markAsDead <integer>index

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.

<integer>index: The index of the vertex to mark as dead.

<integer>numberPointsInFace <integer>index

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.

<integer>index: The index of the face to inspect.

<integer>getVertexIndexFromFace <integer>faceIndex <integer>ithVertex

<integer>faceIndex : The index of the face to inspect.

<integer>ithVertex: The I-th vertex of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.

<integer>getHandleIndexFromFace <integer>faceIndex <integer>ithVertex

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.

<integer>faceIndex: The index of the face to inspect.

<integer>ithVertex: The I-th handle of that you want to retrieve. This value should range from 1 to the number of vertices*2 that the face contains.

<integer>getInteriorIndexFromFace <integer>faceIndex <integer>ithVertex

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.

<integer>faceIndex : The index of the face to inspect.

<integer>ithVertex: The I-th interior handle of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.

<integer>getVertexGeomIndexFromFace <integer>faceIndex <integer>ithVertex

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

<integer>faceIndex: The index of the face to inspect.

<integer>ithVertex: The I-th vertex of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.

<integer>getHandleGeomIndexFromFace <integer>faceIndex <integer>ithVertex

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

<integer>faceIndex: The index of the face to inspect.

<integer>ithVertex: The I-th handle of that you want to retrieve. This value should range from 1 to the number of vertices*2 that the face contains.

<integer>getInteriorGeomIndexFromFace <integer>faceIndex <integer>ithVertex

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

<integer>faceIndex: The index of the face to inspect.

<integer>ithVertex: The I-th interior handle of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.

<void>setFaceVertex <point3>pos <integer>faceIndex <integer>ithVertex <boolean>sel

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.

<point3>pos: The position that you want to move a vertex to.

<integer>faceIndex: The index of the face that you wish to work on.

<integer>ithVertex: The ith vertex of the face that you want to change

<boolean>sel: Whether or not to select the vertex after it is recreated

<void>setFaceHandle <point3>pos <integer>faceIndex <integer>ithVertex <boolean>sel

This method is identical to SetFaceVertex except works on patch handles.

<point3>pos: The position that you want to move a vertex to.

<integer>faceIndex: The index of the face that you wish to work on.

<integer>ithVertex: The ith vertex of the face that you want to change

<boolean>sel: Whether or not to select the vertex after it is recreated

<void>setFaceInterior <point3>pos <integer>faceIndex <integer>ithVertex <boolean>sel

This method is identical to SetFaceVertex except works on patch interior handles.

<point3>pos : The position that you want to move a vertex to.

<integer>faceIndex : The index of the face that you wish to work on.

<integer>ithVertex : The ith vertex of the face that you want to change

<boolean>sel: Whether or not to select the vertex after it is recreated

<void>setFaceVertexIndex <integer>faceIndex <integer>ithVertex <integer>vertexIndex

This method allows you to set the index of the ith vertex of a face.

<integer>faceIndex : The index of the face that you wish to work on.

<integer>ithVertex : The ith vertex of the face that you want to manipulate.

<integer>vertexIndex: The index into the vertex list that you want to set.

<void>setFaceHandleIndex <integer>faceIndex <integer>ithVertex <integer>vertexIndex

This method is identical to setFaceVertexIndex but works on handles for patches.

<integer>faceIndex: The index of the face that you wish to work on.

<integer>ithVertex: The ith vertex of the face that you want to manipulate.

<integer>vertexIndex: The index into the vertex list that you want to set to

<void>setFaceInteriorIndex <integer>faceIndex <integer>ithVertex <integer>vertexIndex

This method is identical to setFaceVertexIndex but works on interior handles for patches.

<integer>faceIndex: The index of the face that you wish to work on.

<integer>ithVertex: The ith vertex of the face that you want to manipulate.

<integer>vertexIndex: The index into the vertex list that you want to set to

<void>updateView()

This method forces the viewport and dialog to update.

<void>getFaceSelectionFromStack()

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 Class IunwrapMod, in the SDK Help file accompanying this product.


uvwMappingHeightManip interfaces:

Interface: Manip

Properties

.mouseState : enum : Read

mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods

<void>clearGizmos()

This must be called at the beginning of the "updateGizmos" handler in order to clear the current gizmo cache.

<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by value>selColor

This creates a gizmo from a mesh (or geometry in 3ds max lingo). The mesh can be any arbitrary 3ds 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.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>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.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

marker enums: {point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by addGizmoShape.

<point3 by value>position : The position is a point in 3d space, or 2d screen space.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>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.

<ray by value>getLocalViewRay <point2 by value>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.

<void>updateGizmos <time>t <&TSTR>toolTip

See also

Scripted Manipulators

Interface: manip

radiusManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper

sliderManipulator interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:


uvwMappingLengthManip interfaces:

Interface: Manip

Properties

.mouseState : enum : Read

mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods

<void>clearGizmos()

This must be called at the beginning of the "updateGizmos" handler in order to clear the current gizmo cache.

<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by value>selColor

This creates a gizmo from a mesh (or geometry in 3ds max lingo). The mesh can be any arbitrary 3ds 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.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>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.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

marker enums: {point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by addGizmoShape.

<point3 by value>position : The position is a point in 3d space, or 2d screen space.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>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.

<ray by value>getLocalViewRay <point2 by value>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.

<void>updateGizmos <time>t <&TSTR>toolTip

See also

Scripted Manipulators

Interface: manip

radiusManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper

sliderManipulator interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:


uvwMappingUTileManip interfaces:

Interface: Manip

Properties

.mouseState : enum : Read

mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods

<void>clearGizmos()

This must be called at the beginning of the "updateGizmos" handler in order to clear the current gizmo cache.

<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by value>selColor

This creates a gizmo from a mesh (or geometry in 3ds max lingo). The mesh can be any arbitrary 3ds 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.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>selColor

This creates a gizmo from a shape object. The gizmoShape can be created using functions from the "manip" package, described below.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

marker enums: {point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

The creates a gizmo using a marker.

<point3 by value>position : selColor The position is a point in 3d space, or 2d screen space.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>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.

<ray by value>getLocalViewRay <point2 by value>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.

<void>updateGizmos <time>t <&TSTR>toolTip

See also

Scripted Manipulators

Interface: manip

radiusManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper

sliderManipulator interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:


uvwMappingVTileManip interfaces:

Interface: Manip

Properties

.mouseState : enum : Read

mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods

<void>clearGizmos()

This must be called at the beginning of the "updateGizmos" handler in order to clear the current gizmo cache.

<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by value>selColor

This creates a gizmo from a mesh (or geometry in 3ds max lingo). The mesh can be any arbitrary 3ds 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.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>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.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

marker enums: {#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

This method creates a gizmo using a marker.

<point3 by value>position : The position is a point in 3d space, or 2d screen space.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>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.

<ray by value>getLocalViewRay <point2 by value>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.

<void>updateGizmos <time>t <&TSTR>toolTip

See also

Scripted Manipulators

Interface: manip

radiusManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper

sliderManipulator interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:


uvwMappingWidthManip interfaces:

Interface: Manip

Properties

.mouseState : enum : Read

mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods

<void>clearGizmos()

This must be called at the beginning of the "updateGizmos" handler in order to clear the current gizmo cache.

<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by value>selColor

This creates a gizmo from a mesh (or geometry in 3ds max lingo). The mesh can be any arbitrary 3ds 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.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>selColor

This creates a gizmo from a shape object. The gizmoShape can be created using functions from the "manip" package, described below.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

marker enums: {#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by addGizmoShape.

<point3 by value>position : The position is a point in 3d space, or 2d screen space.

<integer>flags: Use one of the following values:

0: gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

1: gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

2: gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

3: 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.

4: 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.

<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>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.

<ray by value>getLocalViewRay <point2 by value>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.

<void>updateGizmos <time>t <&TSTR>toolTip

See also

Scripted Manipulators

Interface: manip

radiusManip interfaces:

ConeAngleManip - superclass: helper

PlaneAngleManip - superclass: helper

Scripted Plug-ins

sliderManipulator - superclass: helper

sliderManipulator interfaces:

uvwMappingHeightManip interfaces:

uvwMappingLengthManip interfaces:

uvwMappingUTileManip interfaces:

uvwMappingVTileManip interfaces:

uvwMappingWidthManip interfaces:


UVWUnwrap interfaces:

See

Unwrap_UVW interfaces:


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

Source Code Layout

Entering Information into MAXScript

Assigning Variables

Mathematical Operations in MAXScript

Working with 3ds max Objects

Drawing a Box with MAXScript

Modifying the Box

Applying Standard Transformations

More Box Transformations

Creating Your Own Scripts

The Script Editor

Controlling Program Flow in Scripts

Defining Custom Functions

Structure Definitions

3ds max Commands in MAXScript

Where to Go From Here

Saving your Commands in a Script File

Loading and Running Your Script File

Loading Other Scripts

Learning MAXScript by Walking Through a Script

Learning MAXScript with the Macro Recorder

Some Advanced Topics Include:

Action Manager

ActiveX Controls in MAXScript Rollouts

Asset Browser enhancements

Curve Control

Customize The Order of Rollup Pages

General Event Callback Mechanism

iDrop - drag and drop

Interfaces

Menu Manager

Network Render Interface

Parameter Wiring

Quad Menu

Scripted Custom Attributes

Scripted Manipulators

Visual MAXScript

Zip-file Script Packages


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:

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.

Next Topic

Source Code Layout


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.

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:

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:

Next Topic

Entering Information into MAXScript


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.

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.

  2. Write the word "Hello" again, this time with quotation marks, and press ENTER.

    The command output is now "Hello".

    It seems that MAXScript knows the string "Hello" because it answers with a friendly "Hello." Actually, it merely knows that you entered a string, and the command output for strings is always the value of the string you entered.

Entering Arrays in MAXScript

You can use an array to group several elements into one collection. An array is an ordered collection of values. In MAXScript, each element in the array can contain any type of value, and all of the elements can be accessed individually.

An array can be expressed in two forms. The first is:

#()

This is the most basic type of array: an empty one. It is important to note that all arrays must be defined with the pound character (#) and a pair of parentheses.

#( <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.

Next Topic

Assigning Variables


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.

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:

  1. 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.

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.

Next Topic

Mathematical Operations in 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.

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 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 topic in the MAXScript reference.

Creating Random Numbers

One very useful mathematical operation in MAXScript is the random number function. It returns a pseudo-random number selected inclusively between two user-specified arguments. For example:

random 1 100

returns a random integer between 1 and 100. The return value type (Float or Integer) is the same as the type of the first argument in the function, therefore if you enter:

random 1.0 100

MAXScript returns a random float between 1 and 100.

Note: For reasons beyond the scope of this tutorial, the random command will generate the same 'random' numbers each time a script is run. This happens if you restart the software and run the script, but not if you run the script over and over. If you want the values created by the random function to change each time you start the software, you can use the seed command:

seed <number>

where <number> is any float or integer. Each time you change the seed value, MAXScript generates new 'random' numbers.

Incrementing

Another useful mathematical operation that MAXScript provides is incrementing. This is a shorthand form of assignment that can be used to modify a value in place, as shown in the following long form examples:

x = x + 1

There are assignment operators corresponding to the four math operations (+,-,*, and /) that apply the operation to the assignment's destination with the result. Their syntax is:

<destination> += <expr> -- add <expr> to destination

<destination> -= <expr> -- subtract <expr> from destination

<destination> *= <expr> -- multiply destination by <expr>

<destination> /= <expr> -- divide destination by <expr>

Using this shorthand form of assignment, the previous example can be written as:

x += 1

Next Topic

Drawing a Box with MAXScript


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

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 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 [image] 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.

MAXScript also draws the box in the viewports, as shown in this perspective viewport:

Notice that you can use [image] Undo (as you can with most MAXScript creation and modification commands) to remove the box from the scene.

Next Topic

Modifying the Box


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.

Changing Object Properties

Object Name

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:

Color

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 [image] Undo to change the box back to blue.

For more information on colors, see the Color Values topic in the MAXScript reference.

Position

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:

Click [image] Undo to move the box back to the origin.

Size

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.

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:

Although altering the height and width properties of the box achieves the same result, visually, the above scale modification is not equivalent to using the following two commands:

mybox.height = 40 -- 2 times the original 20 units
mybox.width = 60 -- 3 times the original 20 units

The reason for this is that changing the height property of the box changes the creation parameter of the box's height. Using the scale property to transform the height of the box does not.

Again, the effect of using either method is visually the same. However, 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 [image] Undo twice to change the box back to its original height and width.

Finding Additional Parameters

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

The showClass() function prints information about a specified 3ds max class or classes. The information entered in the parentheses is a string containing a wild-card pattern to match against 3ds max class names, superclass names, and property names.

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:

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 all of the parameters of the Box and the BoxGizmo classes.

Examples:

showClass "box*" -- all 3ds max classes starting 'box'

showClass "box.*" -- all the accessible properties of the

-- box class

showClass "*:mod*" -- all the modifier classes

showClass "*.*rad*" -- all the classes with a property name

-- containing 'rad'

The second inspector function is showProperties(). The showProperties() function is used to display the properties for a specific object that is an instance of one of the 3ds max 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 that may appear in individual objects as you work on them in the scene.

To learn more about these functions, search for the "Class and Object Inspector Functions and Properties" topic in the MAXScript Reference.

Next Topic

Applying Standard Transformations


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.

Moving 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.

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 [image] Undo three times to move the box back to its original position.

On the other hand, entering:

move mybox [10,0,0]

move mybox [10,0,0]

move mybox [10,0,0]

will move your box 30 units along the X-axis.

If you entered the above commands, click [image] Undo three times to move the box back to its original position.

Scaling 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.

Rotating 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 document 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

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 [image] 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 topic in the MAXScript reference.

Next Topic

More Box Transformations


More Box 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.

Creating and Assigning Modifiers

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

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:

Changing 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

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 [image] Undo twice to bring the box back to its original state.

Animating the Box

MAXScript has several syntax forms that mirror the main UI tools, such as the Animate button, the time slider, and the active coordinate system. In the following example, you turn on the Animate button, set the slider to several different values, and adjust the properties of your box, just as you would do using the software's UI:

animate on

(

at time 0 (mybox.pos = [-100, 0, 0]; mybox.scale = [1, 1, 0.25])

at time 100 (mybox.pos = [100, 0, 0]; mybox.scale = [1, 1, 3])

)

Drag the slider around, and you will see that MAXScript has animated the box, and placed keyframes at 0 and 100.

When you use MAXScript to animate objects, the actual Animate button in the UI does not come on, nor does the time slider move; these things happen within MAXScript.

In this example, the time was given as a simple number. If no unit is specified, MAXScript interprets this as a frame number. You can also use one of the various time literals in the following manner:

2.5s -- 2.5 seconds

20f -- 20 frames

4800t -- 4800 ticks = 1 sec

1m3s5f -- 1 min, 3 seconds, 5 frames

1:15.5 -- SMPTE: 1 min, 15 seconds, 5 frames

Note: All times are automatically converted to frames.

Next Topic

The Script Editor


The Script Editor

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.

Thus far in this tutorial, you have been performing all of the script examples in the MAXScript Listener, however when you are writing or editing a script of your own, you will use the Script editor.

The main difference between the Script Editor and the Listener is that the Listener can only evaluate one set of information at a time. However, you can enter long, complex scripts in the Script Editor and evaluate them piece-by-piece or all at once.

Scripts are entered using the same syntax and rules, however they are not executed upon pressing ENTER. 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.

Navigating the Script Editor

The Script editor contains several useful tools for navigating and error-checking large scripts.

Tabs

You can use the TAB key to create blocks in your script. This makes it easier to read the script and to keep track of parentheses, which you use to create blocks of commands.

CTRL-Right Click Navigation

When you press CTRL+Right-click, a menu is displayed which allows you to jump to any specific event or UI item in the script.

Bracket Balance

In complex scripts, it is common to lose track of blocks of commands, causing you to add extra parentheses or leave them out. You can find these errors by pressing CTRL+B. MAXScript will highlight the block that your cursor is on, showing you the start and end parentheses.

Color Coding

You can tell MAXScript to display different elements of your script in different colors, making it easier for you to navigate your script at a glance. When you press CTRL+D, MAXScript will color-code your script in the following manner:

Comments – Green

Events (such as on, if, or while) – Blue

Text strings – Dark Red

The rest of the script remains black.

Note: Color-coding does not update automatically. As you add to or change a script, you will need to press CTRL+D again to update the color-coding.

Next Topic

Controlling Program Flow in Scripts


Controlling Program Flow in Scripts

MAXScript provides commands that allow you to control the path that the software follows it evaluates your script. The two most useful groups of commands are the conditional statements and loop statements.

Conditional Statements

Conditional statements simply tell MAXScript to perform a specified command if a certain condition is met. For example:

if mybox.height == 10 then mybox.width = 20

This changes the width of your box to 20 if its height is equal to 10. You may have taken note of the double equal sign used in the statement above. This is discussed at the end of this topic.

This "if…then…" statement can be expanded to include an "else" statement. For example:

if mybox.height == 10 then mybox.width = 20 else mybox.width = 10

This statement tells MAXScript to change the width of your box to 20 if its height is 10, otherwise change the width to 10. The "if," "then," and "else" portions of the statement can all be on separate lines:

if b.height == 10

then b.width = 20

else b.width = 10

If you are entering these commands into the Listener window, you may notice that the commands are not executed line by line, as is typical of the Listener. This is because the Listener recognizes that the "if" statement requires a "then" statement to be complete. In fact, the Listener does not execute the statement after the "then" statement, because it does not know if you intend to include an "else" statement. For this reason, the Listener does not execute an "if…then…" statement until you have either entered a "then" statement or after the next line you type, following the "if…then…" statement.

The double equal sign in the last statement, "==," tells MAXScript to compare two values. The single "=" sign always signifies assignment. This is common in many standard programming languages, such as C++. There are several different conditional parameters used in MAXScript. They are listed here:

== equal to

!= not equal to

> greater than

>= greater than or equal to

< less than

<= less than or equal to

Note: Any time MAXScript evaluates a conditional expression, the result is either true or false. MAXScript temporarily stores the value of this result. In an "if…then" statement, MAXScript uses this result to determine the path to follow in the statement. If the result of the "if" statement is true, MAXScript will evaluate the "then" expression. If the result is false, MAXScript will evaluate the "else" expression, assuming one is specified; otherwise, it will cease evaluating the conditional statement. In some scripts, you might see the words on and off used in place of true and false, respectively. These words are interchangeable and they mean the same thing to MAXScript.

Loops

Loops are repetitive operations that tell MAXScript to repeat the execution of a collection of commands. Loops are useful for working with large groups of objects, as you can make changes to many objects with one set of commands. For example, if you wanted to make 50 boxes, you could use a loop to execute the create command 50 times, rather than creating the boxes with 50 separate commands. Loops are also useful for changing the properties of multiple objects.

There are several different types of loop. The first to be considered are for and while loops.

For Loops

The for loop iterates through a range of numbers, time values, or a sequenced collection of values, such as an array or object set. Use a for loop to copy the box:

for i = 1 to 5 do

(

box_copy = copy mybox

box_copy.pos = [i * 50, 0, 0]

)

Everything inside of the parentheses makes up a "block". All loop statements must be created as a block. This statement executes five times. Each time, a new box is created.

A for statement starts with the word 'for'. Next, you must define how many times the statement will repeat. In this case, you have used the variable "i" to control the loop. The line, "for i = 1 to 5" tells MAXScript to set the variable "i" to the value 1, execute the contents of the loop statement, then set the variable "i" to 2, execute the loop contents, and so on. The variable "i" is called the index for the loop. Each time the loop executes, the index is incremented by 1 automatically, without requiring any user input. Each repetition of the loop is called an iteration. To make MAXScript increment the index by a value other than 1, insert 'by x' after the index statement, where x is the amount to increment the index. For example, the following statement will set the index to 1, then 3, then 5:

for i = 1 to 5 by 2 do

(

box_copy = copy mybox

box_copy.pos = [i * 50, 0, 0]

)

The "do" keyword tells MAXScript to execute the following block or statement each time the loop repeats. Note that in some loops you might see the word "in" in place of the equal sign, "=". These both mean the same thing in for loops, and can be used interchangeably. Note how the index was used within the loop statement to set the position of each new box. This is a useful way to work with multiple object creation.

For loops can also be used to build arrays and/or access values within an array. In the following example, you use a for loop to build an array called 'arr':

Remember that because MAXScript is an expression-based language, you are able to use expressions in variable assignment, as seen above in the assignment of the for loop expression to the variable, arr. Note the 'collect' statement in the for loop above. This tells MAXScript to collect the results of each iteration in an array, rather than just calculate them. In this case, you only asked MAXScript to collect the value of the index; however, you can collect iterations of any expression.

Finally, for loops can also perform iterations with the contents of an array. In the following example, you use a for loop to access the values of the array you created in the previous example:

The 'print' command is a MAXScript function that displays the specified variable in the Listener window. In this example you used 'in' instead of an equal sign; however, they are still both acceptable, even when accessing values within an array.

Note: You can also access the number of elements in an array with the .count property. For example, the previous example could have been written:

for i = 1 to arr.count do print i

This will return the same result.

While and Do Loops

While and Do loops are used to repeatedly execute an expression until a test expression evaluates as false. The while and do loop are simple variants of one another. The syntax is:

do <expr> while <expr> -- do loop

while <expr> do <expr> -- while loop

The following example will return the value of a variable, incrementing the variable by –1 with each iteration.

x=10

while x>0 do print (x-=1)

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

Next Topic

Defining Custom Functions


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

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:

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

Next Topic

Structure Definitions


Structure Definitions

In addition to custom functions, you can also create custom compound values in MAXScript using "structure definitions". Structure definitions are a flexible data type, built of simpler data types. They let you define the layout of a new structured type of value that you can then create and work with in your code. The syntax for a structure definition is:

Struct <struct_name> ( <member> , <member> )

where each <member> can be one of:

<name> [ = <expr> ] – name and optional initial value

<function_definition>

Create a new structure, called person:

Struct person (name, height, age, sex)

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.

Next Topic

3ds max Commands in MAXScript


MAX Commands in 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 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

Next Topic

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 topic (mybox = box length:20 width:20 height:20)

  4. Press CTRL+C on your keyboard to copy the text to the Clipboard.

  5. Click the Script Editor window to place the cursor in it, and press CTRL+V on your keyboard to paste the command into the Script Editor window.

    Tip: You can also drag selected text from the Listener and drop it in the Script Editor, or vice versa.

  6. Choose File > Save in the Choose File Name for Save dialog, navigate to your \Scripts directory. Name your script file box_draw.ms and click Save.

    Your script file is saved and the script editor window title changes to "box_draw.ms - MAXScript."

You have now saved your first script file. MAXScript uses the .ms extension for script files. It is good general practice to save all of your script files into the scripts directory.

Next Topic

Loading and Running your Script File


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.

  3. Select the box_draw.ms file, and click Open.

    MAXScript immediately carries out the command that is contained in the script file and places a box in the scene.

To open a script file for editing:

If you want to edit your script later to add more commands to it, you need to open it:

  1. In the MAXScript rollout, click the Open Script button

  2. Select the script you want to edit and click Open.

    The Script Editor window opens, showing the text of your script. You can now edit your commands or add new ones, as you would edit any other text file. Save the script file to keep your changes.

To evaluate the commands in your script:

If you enter any commands in the Script Editor window manually (not by copying and pasting from the Listener window), you can test the validity of all commands:

  1. If your Listener window isn't open, click the Open Listener button in the MAXScript rollout.

  2. In the Script Editor window, choose File > Evaluate All.

    MAXScript evaluates the commands in your script file. It sends any feedback to the Listener window. It also sends each valid command to the user interface as if you had run the script. If your script contains any syntax errors, MAXScript reports those in the Listener window in red.

To include your script in another script:

If you want to write a script for each tutorial (for example one for drawing a box, one for modifying the box, and another one for transforming it), you could then use those three scripts in another one that contains all the box operations. Assuming you had created the scripts box_draw.ms, box_mod.ms, and box_trans.ms, you could then include them in a new script, box_all.ms. The text for box_all.ms would be as follows:

include "box_draw.ms"

include "box_mod.ms"

include "box_trans.ms"

To reset 3ds max before running scripts:

If you want to start with a new scene before running any scripts, you need to reset the software:

  1. Choose File > Reset.

  2. Answer the Yes-No prompt to either save or discard the changes to your scene.

  3. Open and run the script you want.

    Note that resetting the software closes all MAXScript windows so that you can't copy any more commands from the Listener window. You can always copy commands from the help file, as described below.

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.

Next Topic

Loading Other Scripts


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.

Next Topic

Learning MAXScript by Walking Through a Script


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.

    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 topic in the MAXScript Reference.

Next Topic

Learning MAXScript with the Macro Recorder


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 topic in the MAXScript reference.


The Scripts Included with the Software

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.


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

Punctuation and Symbols

Reserved Global Variables


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

Reserved Keywords

about

and

animate

as

at

by

case

catch

collect

continue

coordsys

do

else

exit

fn

for

from

function

global

if

in

local

macroscript

mapped

max

not

of

off

on

or

parameters

persistent

plugin

rcmenu

return

rollout

set

struct

then

throw

to

tool

try

undo

utility

when

where

while

with

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 MAXScript Grammar. Some of these punctuation marks and symbols offer more information. Click a linked punctuation mark or symbol to go to a description of its usage. In some cases, a keyword may have more additional meanings, depending on its context.

(

)

+

*

-

/

^

+=

-=

*=

/=

--

=

;

<eol>

,

[

]

:

'

&

.

{

}

#

==

!=

<

>

>=

<=

?

$

...

..

\


Reserved Global Variables

Reserved global variables are variables to which MAXScript automatically assigns values. The MAXScript reserved global variables fall in 3 categories: predefined globals (such as red and pi); 3ds max system globals which give you access to state information in the 3ds max system (such as currentFrame); and MAXScript system globals which give you access to the MAXScript system state.

Unlike language reserved keywords, you can re-use these variable names as local variables, with values that you specify. However, it is highly recommended that you do not re-use reserved global variable names as such usage can be highly confusing.

See also

Predefined Globals

3ds max System Globals

MAXScript System Globals

Variables – Assignment and Scope


Predefined Globals

The predefined global variables contain special values that are frequently used in scripts. These variables are read-only.

true, false

Boolean values. Can be used for testing the results of comparisons and for state tests.

on, off

Synonyms for true and false, sometimes easier to read in state accesses.

pi, e

Float values that contain the standard mathematical constants' values. They are equivalent to 3.1415926535 and 2.718281828, respectively.

red, green, blue, white, black, orange, yellow, brown, gray

A predefined set of useful Color values.

x_axis, y_axis, z_axis

Point3 values that define normal vectors for the 3 major axes. They are equivalent to [1, 0, 0], [0, 1, 0], and [0, 0, 1], respectively.

ok

A void value returned by some functions or expressions that don't have a meaningful value to return.

undefined

The initial value of all variables and array elements. MAXScript generates an error if you try to perform any operation on the undefined value, except for checking to see if some value is equal to it or not:

if a == undefined then print "oh, oh"

if b != undefined then print "whew!"

unsupplied

The initial value of all function keyword arguments. Keyword arguments are optional arguments to functions. If a keyword argument is not supplied by the function caller and the function definition does not specify a default value, MAXScript initializes the keyword argument to unsupplied. You can test for this value to see whether a caller has supplied a particular keyword. For more details, see Function Calls.

dontcollect

This value is used in for loops to signal that the value is not to be collected. See For Loop for details.


3ds max System Globals

The 3ds max system global variables give you access to state information in the 3ds max system. Except where noted as read-only, you can both access and assign to the global variables.

activeGrid

Contains the currently active grid. If the home grid is active, returns the value undefined. You can assign a grid node object to this variable to make it the currently active grid. See Viewport Grids.

You can also return to the home grid by setting activegrid = undefined.

ambientColor

Lets you get and set a Color value that defines the global rendering environment (Rendering > Environment) ambient lighting color. See Working with 3ds max Atmospherics.

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.

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.

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.

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.

autoBackup.enabled

Get/set whether auto backup is enabled as a <boolean>.

autoBackup.time

Get/set the time in minutes between auto backup as a <float>. If the specified value is < 0.01 (the UI limit), the time is set to 0.01.

backgroundColor

Lets you get and set a Color value that defines the global rendering environment (Rendering > Environment) background color. See Working with 3ds max Atmospherics.

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.

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.

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.

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.

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.

flyOffTime

Lets you get and set an Integer value that defines the time in milliseconds the user must hold down on a flyout before the flyout is activated. This variable contains the corresponding value set in the General tab of the Preferences dialog.

frameRate

Lets you get and set an Integer value that defines the current scene frame rate in frames-per-second. This variable contains the corresponding value set in the Time Configuration dialog. See Time Configuration Dialog.

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.

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.

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.

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.

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.

listener

Read only system global - listener edit window <WindowStream> value

localTime

Contains a String value that defines the current local date and time. This variable is read-only. An example of the value stored in localtime is:

s = localTime

"4/14/97 10:24:57 AM"

The format of this string is controlled by the date format selected in the main Windows Regional Settings control panel.

logsystem.quietmode

Lets you get and set whether error logging quiet mode is enabled. A Boolean value set to true when you do not want error messages from the renderer to bring up dialog boxes. If set to false, error messages from the renderer will bring up dialog boxes. 3ds max sets the 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. See Material Editor 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.

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.

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 Modify Panel.

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.

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.

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 and Render Scene Dialog.

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.

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.

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.

scriptsPath

Contains a String value that defines the full directory path to the current Scripts directory. This variable is read-only.

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 SelectionSetArray Values.

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 Modify Panel.

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.

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.

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.

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 Modify Panel. For example:

b=box() -- create a box

em=edit_mesh() -- create an Edit Mesh modifier

addModifier $box01 em -- add edit mesh mod

max modify mode -- open mod panel

select $box01 -- select object box01

print subObjectLevel -- print the current subobject level

subObjectLevel = 2 -- set sub-object level to Edge

sysInfo.DesktopSize

A read only variable to get the desktop size in pixels as a <point2> value.

sysInfo.DesktopBPP

A read only variable to get the desktop color depth in bits per pixel as an <integer> value.

sysInfo.MAXPriority

Get/set the 3ds max process priority as a <name> value. Valid priority values are #high, #normal, and #low

ticksPerFrame

Contains an Integer value defining the system time resolution. This variable is read-only.

timeConfiguration.playActiveOnly

Lets you get and set whether to playback the active viewport only. This variable contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Active Viewport Only is on, false if off. See Time Configuration Dialog.

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.

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.

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.

units.DisplayType

Get/set the current unit display type as a <name>. Valid unit display types are:

#Generic

#Metric

#US

#custom

units.MetricType

Get/set the current metric unit display type as a <name>. Valid metric unit display types are:

#Millimeters

#Centimeters

#Meters

#Kilometers

units.USType

Get/set the current US standard unit display type as a <name>. Valid US standard unit display types are:

#Frac_In

#Dec_In

#Frac_Ft

#Dec_Ft

#Ft_Frac_In

#Ft_Dec_In

units.USFrac

Get/set the current US fraction display type as a <name>. Valid US fraction display types are:

#Frac_1_1

#Frac_1_2

#Frac_1_4

#Frac_1_8

#Frac_1_10

#Frac_1_16

#Frac_1_32

#Frac_1_64

#Frac_1_100

units.CustomName

Get/set the current custom unit name as a <string>

units.CustomValue

Get/set the current custom unit value as a <float>

units.CustomUnit

Get/set the current custom unit type as a <name>. Valid custom unit display types are:

units.SystemScale

Get/set the current system unit scale value as a <float>. This is the value shown in Preference Settings, General tab, System Unit Scale group.

units.SystemType

Get/set the current system unit scale type as a <name>. This is the unit shown in Preference Settings, General tab, System Unit Scale group. Valid system unit scale types are:

#Inches

#Feet

#Miles

#Millimeters

#Centimeters

#Meters

#Kilometers

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.

videoPostTracks

Contains a MAXTVNode value that defines the top-level Video Post Track View node. This variable is read-only. See Track View Nodes. 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.

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.

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 3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters.

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.


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.

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.

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 Memory Allocation and Garbage Collection.

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 Using the '?' Symbol.


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

Scope of Variables

Persistent Global Variables

Type-Free Variables

Reference Assignment

Memory Allocation and Garbage Collection

Manual Garbage Collection


Variable Assignment

The syntax for general assignment, <assignment>, is:

<destination> = <expr>

where <destination> can be one of:

<var_name>

<property>

<array_index>

Each of these destination type is described below.

MAXScript provides a swap() method that takes two valid assignment destinations as arguments and swaps their values. Its syntax is:

swap <destination> <destination>

Assignment to Variables

A variable is identified with a MAXScript <var_name>, as described in Names. If <destination> is a var_name, it identifies the variable to be assigned a value, as shown in the following examples:

x = 2 + 2 * 3 -- assign to variable x

y = [1, 2, 3] + pos -- assign to variable y

z = #(1, 2, "foo", "bar") -- assign to variable z

z = #oops -- oops, changed my mind

Assignment to Accessors

If <destination> is a <property> or an <array_index>, the assignment is to an accessor. Accessors are constructs used to access the components in compound values, such as arrays and 3D points. There are two kinds of accessors corresponding to the two kinds of compound values in MAXScript:

  • The component values are arranged in an indexable sequence, as in arrays or strings.

  • The compound value contains a fixed set of named components, as with 3D points and time intervals.

All 3ds max objects, such as boxes, spheres, bend modifiers, or bitmap textures are treated as compound values in this sense. All their parameters, such as height and angle, or map file name, are accessed as named components. In MAXScript, these named components are referred to as properties. For more information, see Properties, Methods, Operators, and Literals.

Accessors have one of two forms, an <array_index>:

<operand> [ <expr> ] -- an indexed element

or a <property>:

<operand>.<var_name> -- a named property – property var_name of value in operand

Examples of assignment to accessors are:

$box01.pos = baseObj.pos + (baseObj.radius*[0,0,1])

Set the position property of object box01 based on the position and radius properties of the object whose value is stored in variable baseObj.

z[2] = d.rotation as eulerangles

Convert the rotation property value of the value stored in variable d to an eulerAngles class value, and store this value in element 2 of the array stored in variable z.

Because MAXScript is an origin 1 language, all sequencable collections in MAXScript start at index position 1. This is an important convention to remember when using the indexing operator.

The syntax definitions allow you to use any <operand> before the . or []. Because accessors are themselves operands, this definition is recursive, which means you can string accessors together to query nested arrays or properties:

my_things[i][j]

my_objects[i].target.position.x

Accessors are evaluated left-to-right. The first example evaluates the i'th element of my_things, which is presumably a nested array or an array of strings, before yielding the j'th element of that element.

The second example retrieves an object from an array of my_objects, then its target, then the position of the target (a 3D point), and finally the x coordinate of that point.

An <operand> can also be a block-expression, allowing you to compute the target object to be accessed. For example:

(instance myNode).pos=myNode.parent.pos

Create an instance of the node whose value is stored in variable myNode, and set its position to the position of the myNode's parent object.

(find_table "foo")[n - 2] = "fred"

Call function find_table with a parameter value of "foo". The return value from the function is presumably an array. Set element n-2 of this array to the value "fred".

The named properties defined for the MAXScript values and classes are documented with the value and class descriptions.

Order of Evaluation

In an assignment, <expr> is evaluated before <destination>, as can be seen in the following example:

Script

a=#() -- create an empty array to play with

a[(print "in <destination>";1)]=(print "in <expr>";10)

Output

#() -- result line 1

"in <expr>" -- output from <expr> side of assignment

"in <destination>" -- output from <destination> side of assignment

10 -- result line 2

Assignment in MAXScript is itself an expression and yields the value just assigned. Therefore, you can use assignments inside other expressions or cascade assignments, as in:

x = y = z = 0

#(1, 2, a = [0,0,1], 4)


Scope of Variables

Variables have an attribute called scope, which determines where in MAXScript code a variable can be accessed. MAXScript has two kinds of variable scope, global and local. Global variables are visible in all running MAXScript code and hold their values until you exit 3ds max. Local variables are directly visible to code only in the lexical scope currently in effect, and hold their values only as long as the current scope is active. Once a scope is no longer active, you can no longer access the contents of a variable local to that scope. This is similar to how most modern programming languages implement variables. The conditions under which MAXScript creates a new scope are described next.

MAXScript provides language constructs used to explicitly declare and initialize both global and local variables. The syntax for variable declaration, <variable_decls>, is as follows:

( local | global ) <decl> { , <decl> }

where <decl> is defined as:

<var_name> [ = <expr> ] -- name and optional initial value

Examples

global baz -- initialized to 'undefined'

global foo=10, initialized=false -- initialized globals

local x = 1, -- continued on several lines

y = 2,

z = sqrt(123.7)

As mentioned above, local variables hold their values as long as that scope is active. In nested scopes, this is usually a very short period – it starts when a function or loop or block expression runs and ends when it exits. Each time the scope is entered at runtime, a new set of locals is created and then retired when the scope is exited.

In certain situations, however, the top-level scope can remains active for extended periods and so the locals declared at that top-level hold their values for that extended period. In particular, top-level locals declared in scripted rollouts, utilities, plug-ins, script controllers and Macro Scripts hold their values for as long as the rollout, utility, plug-in, or Macro Script exists. Typically, they remain in existence until you redefine them, so for example when you define a Macro Script and run it for the first time, the top-level scope is created and remains active over any number of subsequent executions unless you redefine the Macro Script. At this point, the existing top-level scope is retired and a fresh one (along with its top-level locals) is created when you next execute the Macro Script. This lets you use top-level locals in these constructs as a kind of private global; the values they hold remain in place over many executions but only code in that construct can see the variable and so it does not conflict with other globals.

Note that in scripted plug-ins, a separate copy of the top-level local scope is created for each instance of the plugin and this scope remains active while that instance remains in existence up until the end of the current 3ds max session.

Note

In 3ds max R2.x, the optional initialization value is applied to global variables only if the declaration creates a new variable. So, for example, if you ran the following script twice, the value of x in the second line would be 10 for the first execution, and 20 for the second execution. In 3ds max R3, the optional initialization value is always applied to global variables.

global x = 10

print x

x=20

If you want to make the global variable initialization conditional in 3ds max R3, use a construct similar to:

global foo; if foo == undefined do foo = 23

If you do not explicitly declare a variable, and the variable name does not exist at a higher scope, MAXScript will create the variable the first time you use it and initialize it to hold the special value undefined. You are not required to explicitly declare a variable, or initialize its value, before you can use it. Variable names not explicitly declared by one of the previous statements are called implicitly declared variables. The scope of implicitly declared variables is the MAXScript scope context currently in effect when the variable is first used. The initial MAXScript scope context is global, and new scope contexts are opened for the following:

  • Top-level open parentheses in a script file or in the Listener

  • Start of a function body

  • Start of a for loop body

  • Start of a utility, rollout, right-click menu, Macro Script, or tool definition

  • Start of a rollout, utility, right-click menu, Macro Script, or tool event handler

  • Start of a when body

Within these new scopes, newly referenced variables will be implicitly declared as local variables. Scope contexts are nested, with the scope of a variable explicitly or implicitly declared at one scope context level extending to all scope contexts below that level. Take for example the following script:

Script

a=10 -- scope context: global

( b=20 -- new scope context: level 1

for i = 1 to 5 do -- new scope context: level 2

( j=random i a

k=random i b

print (j*a+k*b)

) -- end of scope context: level 2

a=a+b

) -- end of scope context: level 1

print a -- back to global scope context

print k

In this script, variable a is first used in the global scope context, and its scope includes scope contexts global, level 1, and level 2. Variable b is first used in scope context level 1, so it is implicitly declared as a local variable and its scope includes scope contexts level 1 and 2. Variables i and j are first used 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

Output

20 -- result of line 1

10 -- result of line 3

context level global - foo= 23 -- output from line 5

OK -- result of line 5

context level 1: foo= 9 -- output from line 11

context level 2: foo= -10 -- output from line 18

a= -0.173648 -- output from line 20

context level 1: foo= -10 -- output from line 23

OK -- result of if expression lines 6 to 24

context level global: foo= 23 -- output from line 26

OK -- result of line 26

This might seem a strange way of over-using a single variable name, but in large programs, these scoping rules can be useful. For example, you may add a new user-interface item and its handlers to a utility script. By explicitly declaring the variables used in the handlers as local, you ensure these variables are independent of any preexisting variables with the same names in the remainder of the script.

When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. There are several reasons for this practice:

  • All the variable names used in the block or function will be together, which makes it easier to find the variable names and helps prevent using incorrect names in the script.

  • If more than one script is executed at the same time (for example, you are running a scripted utility and have a scripted controller in the scene) and both scripts use the same global variable name, the two scripts can interfere with one another. This can cause apparently random failures of one or both scripts.

  • You are sure you are using the correct variable in the event that a variable with the same name has already been declared at a higher scope, and you won't inadvertently change the higher-level variable's value.

  • Values of variables explicitly defined as local are displayed in error call stack trace-backs.

  • In 3ds max R2.5, if a 3ds max class, a MAXScript method, or a MAXScript read-only global variable has the same name as an implicitly declared local variable, a MAXScript runtime error will be generated if an assignment to that variable name occurs. Since the variable name already existed with a global scope, an implicitly declared local variable was not created. Since one or more new 3ds max classes will be created by any third party plug-ins the user has loaded, you were not be able to tell ahead of time if a variable name was a global variable name. In 3ds max R3, if the MAXScript compiler detects that the first reference to such a variable is an assignment, it will implicitly declare a local variable, rather than leaving it as a reference to a read-only system global. For example, executing the following expression in 3ds max R2.5 would result in a value of Box, since Box is a 3ds max object class. In 3DS R3, MAXScript detects that the first use of variable box is an assignment and creates an implicitly declared local variable box. The result of this expression in 3ds max R3 is the value undefined.

(if false do box=10;box)

In the following script, an error was introduced by using undefined variable k in line 7. In the output, the error call stack trace-back shows the value for variable b in function afunc and in the block-expression calling afunc.

Script

fn afunc =

(

local b

b = box()

for i in 1 to 10 do

for j in 1 to 10 do

instance b pos:[i*20,j*30,30*sin(k*36)]

)

--

(

global c=10

local b

b="hello"

afunc()

)

Output

afunc()

-- Error occurred in j loop

-- Frame:

-- k: undefined

-- j: 1

-- called in i loop

-- Frame:

-- i: 1

-- called in afunc()

-- Frame:

-- b: $Box:Box102 @ [0.000000,0.000000,0.000000]

-- called in <block>()

-- Frame:

-- b: "hello"

-- No ""*"" function for undefined

OK

If the same script is run with lines 3 and 12 removed, the following output is generated. Because function afunc and the block-expression are in different MAXScript scope contexts, variable b is implicitly declared as local in each and contain different values. However, because they were implicitly defined, they are not included in the error call stack trace-back.

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

Reference Assignment

Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code

Accessing Locals and Other Items in a Rollout from External Code


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 and saved. If needed, you can install persistent globals in each new file in a #filePreSave callback. See General Event Callback Mechanism for more information.

The following methods are used to show and delete persistent globals variables:

persistents.show()

Displays a list of persistent globals and their value.

persistents.remove <var_name>

Removes the named persistent global from the persistent global pool. The variable remains as a global variable and retains its value.

persistents.removeAll()

Removes all persistent globals from the persistent global pool. The variables remain as global variables and retain their value.

Script

a="Hello world"

persistent global a

persistent global b=box()

persistents.show()

persistents.remove #a

persistents.removeall()

a

b

Output

"Hello world"

OK

$Box:Box02 @ [0.000000,0.000000,0.000000]

a: "Hello world"

b: $Box:Box02 @ [0.000000,0.000000,0.000000]

OK

OK

OK

"Hello world"

$Box:Box02 @ [0.000000,0.000000,0.000000]

Note:

If a persistent global contains a MAXWrapper value, but the class instance is not in the scene, that value is not stored/restored on a file save/load.

Example:

-- persistents - node only

persistent global global_array = #()
global_array[1] = b= box()
global_array[2] = bm= bend()
global_array[3] = sm= standard()
global_array[4] = fog()
global_array[5] = area()
global_array[6] = bezier_float()
global_array[7] = br= bricks()
global_array[8] = lookat()
global_array[9] = blur()
global_array[10] = MapScaler()
--b.material=sm
--addmodifier b bm
--sm.diffusemap=br
persistents.show()
max hold
max fetch

persistents.show()

Remarks:

Only the box is in the array after running this script. If the commented lines are run, the material, modifier, and map are also in the array. MAXScript does not do a full reference-tree dump when it outputs its persistent variables, it just outputs RefIDs for MAX objects and so depends on them being dumped as references by the main file save code.


Type-Free Variables

Variables can hold any type of value, and the value type they hold can change from assignment to assignment. For example, you can store a point3 value, then a float value, and then an array to the same variable. The variables in MAXScript are known as type-free variables, unlike variables in C or Java, which can only hold values of a particular declared type. This freedom makes scripting simpler and more exploratory.

As well as being type-free, variables in MAXScript are also type-safe. This means you cannot perform the wrong operation on a value in a variable, as shown in the following example, where MAXScript prints an error message following the invalid operation:

x = $Box01.position -- a point3 value

x = "foo" -- a string value

x = x + 2 -- try to add a number to a string

Error: Unable to convert 2 to type String


Reference Assignment

MAXScript uses a type of assignment called reference assignment. When you create a value, for example by writing a literal, the memory for that value is allocated and a pointer or reference to the value is placed into the variable rather than the value itself. If you assign that variable's value to another variable, the reference to that value's memory is placed in the new variable. The same applies to assigning a variable's value to an array element or passing it as a function call argument; in all cases the reference is assigned or passed. When you assign a new value to a variable or when a variable goes out of scope, the reference that the variable contained is dropped. When your program has dropped all references to a value's memory, that memory becomes eligible for reclamation.

This is in contrast to value assignment in which a copy of the whole value's memory is made and assigned. Value assignment has one advantage over reference assignment, namely that every time a variable or an array element is re-assigned, the old value's memory space can be immediately 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 Memory Allocation and Garbage Collection.

If you assign a variable's value to another variable, the reference to that value's memory is placed in the new variable. Thus, both variables are actually referencing the exact same value. If you assign a new value to one of the variables, that variable will contain a reference to the new value, and the other variable will contain a reference to the old value. Normally this is the desired behavior, as you don't want both variables to reference the new value. However, a complication occurs if a compound value, like a point3 or array, is referenced by more than one variable, and you assign a new value to a component of the compound value. When you assign a value to a component of a compound value, a new compound value is not created. Therefore any variables that reference the compound value will still point to the same value, and will "see" the changed component value. Examples of this behavior are shown in the following script:

Script

(

a="hello world" -- create a string value, put reference in a

b=a -- put string's reference in b

format "a=%; b=%\n" a b -- and print their values

b="thanks for the fish" -- create a string value, put reference in b

format "a=%; b=%\n" a b -- print values – they are different

b=a -- put string's reference from a in b

a[1]="J" -- change a component value

format "a=%; b=%\n" a b -- print values – they are the same

a=b=[10,20,30] -- assign a point3 value reference to a and b

format "a=%; b=%\n" a b -- and print their values

a.x=-100 -- change a component value

format "a=%; b=%\n" a b -- print values – they are the same

)

Output

a=hello world; b=hello world

a=hello world; b=thanks for the fish

a=Jello world; b=Jello world

a=[10,20,30]; b=[10,20,30]

a=[-100,20,30]; b=[-100,20,30]

OK

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.


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.


Names

Names are used in MAXScript to identify variables, functions, parameters, properties, and so on. Names start with an alphabetic character or "_" (underscore), and can contain any number of alphanumeric characters or "_".

Examples of valid names are:

foo

bar123

this_is_a_very_long_identifier

_heresOneWithStudlyCaps

The following names are not valid:

1object First character not an alphabetic character

pressed? ? is not a valid alphanumeric character

a big number spaces not allowed in names

seven(7) ( and ) are not valid alphanumeric characters

In contrast to most general purpose programming languages, MAXScript names are not case-sensitive. For example, the names in the following list refer to the same variable in MAXScript:

BitMapTexture

bitmaptexture

BITMAPtexture

In syntax descriptions, name identifiers are specified as:

<var_name>

An example of a syntax where a name identifier is specified is:

for <var_name> ( in | = ) <sequence> ( do | collect ) <expr>

In this example, <var_name> specifies the for loop variable.

A name in a program is always interpreted as the name of a variable or parameter and it effectively stands for the current value of that variable or parameter in any expression in which it is used. For example, consider the following script:

i=10

j=i+5

print j

In this script, i and j are variable names. In the first line, the value 10 is assigned to variable i. In the second line, the value 5 is added to the value stored in variable i, and then the result is stored in variable j. In the third line, the value 15 is printed, which is the value stored in variable j.

MAXScript also allows you to work directly with names as values at runtime, as you can with numbers and strings. To write a name value in MAXScript, you preface the name with a "#":

#<var_name>

In syntax descriptions, name values are specified as:

<name>

Name values are primarily used for symbolic parameters in function calls, and many of the built-in functions use them as such. The allowed values specified for symbolic parameters are defined by the function, and are documented with the function. As an example, consider the setBeforeORT() function. Its syntax is:

setBeforeORT <controller> <ORT_type_name>

Sets the Out-of-Range (ORT) type for the controller for the time before the first key. The <ORT_type_name> must be one of the following name values:

#constant

#cycle

#loop

#pingPong

#linear

#relativeRepeat

An example usage of this function is:

setBeforeORT $box01.position.controller #pingPong

Name values can also be used as an index in certain Collections. For example, the index for a ModifierArray can be an integer, name, or string:

$loft01.modifiers[#Optimize] -- access modifier on object loft01 called Optimize

See also

Name Values

Quoted Names

Names set in single quotes allow you to write names that contain illegal identifier characters, such as spaces and other punctuation. They are primarily intended for specifying 3ds max object classes and properties that have special characters in their names.

The form is:

'<any_char_except_quote>' -- for an identifier or property name

#'<any_char_except_quote>' -- for a name literal

'<any_char_except_quote>': -- for a keyword parameter label

Examples:

snow 'starttime(start)':5

b.'lifetime(life)'

$box01.modifiers[#'FFD 4x4x4']

Spaces in Names

Because of the large amount of names in 3ds max that include spaces, the underscore character ("_") can be used instead of a space in a name. The following is equivalent to the last line of the above example:

$box01.modifiers[#FFD_4x4x4]


Literal Constants

MAXScript has many built-in data types: numbers, strings, names, arrays, vectors, and matrices, as well as special data types which store the 3ds max objects such as geometry objects, splines, materials, modifiers, etc. Some data types have special literal constant forms, where the literal constant is a value that is keyed directly into your program where it is needed. The syntax of the literal constant specifies both its value and data type. In MAXScript, the assignment of a literal constant might look like this:

b=50

In this line, b is the variable name, and 50 is the literal constant of type integer assigned to b. 50 is a literal constant because you cannot assign a value to 50, and its value cannot be changed.

See also

Number Literals

String Literals

Time Literals

Pathname Literals

2D and 3D Point Literals

Array Literals


Number Literals

MAXScript uses two types of numbers:

  • single precision floating point

  • 32 bit signed integers

These number types correspond to the two number types (Integer and Float) used internally in 3ds max. The syntax for numbers is:

[-]{<digit>}[.{<digit>}[(e | E)[+ | -]{<digit>}+] -- decimal number

0x{<hex_digit>}+ -- hexadecimal number

Examples:

123

123.45

-0.00345

1.0e-6

0x0E

.1

See also

Number Values


String Literals

String literals in MAXScript are one or more characters enclosed in double quotes:

"3ds max"

"October 5th, 1996"

String literals can contain any character except another plain double quote. You can include a double quote in a string literal, as well as some useful control characters, by using a "\" (backslash) escape character sequence. The valid escape sequences are:

\" -- a double quote character

\n -- a newline character

\r -- a carriage return character

\t -- a TAB character

\* -- an asterisk character

\? -- a question mark character

\\ -- a single "\" character

\% -- a percent character

\x{d} -- a hexadecimal character

Example

print "foo should be quoted like this: \"foo\" and a new line: \n"

would output:

"foo should be quoted like this: "foo" and a new line:

"

A "\" character that does not preface one of the specified characters is left as a single backslash.

You can break a string literal into several lines and the line breaks will stay in the string. For example:

"Twas brillig and the slithy tobes

did gyre and gimbol in the wabe

or something like that..."

Non-Printing Characters in Strings

You can specify non-printing characters in string literals using the \x hexadecimal escape sequence convention from C/C++. The form is:

\x{<hex_digit>}+ -- <hex_digit> is a hexadecimal digit (0-9,a-f)

Example:

str = "Copyright \xa9 1997, FrabWorks, Inc"

would insert a copyright sign ©. Hexadecimal a9 is the code for that symbol.

Running the following script displays in Listener the characters associated with each hexadecimal code:

Example:

char="0123456789abcdef"

for i=1 to char.count do

for j=1 to char.count do

(

s=execute("\"\\x"+char[i]+char[j]+"\"")

format "%% %\n" char[i] char[j] s

)

File Path Name Strings

File path name strings use the backslash character to separate a parent directory from its sub-directory. The backslash is used as an escape character, therefore file path names specified in a string should use the escape character sequence for a single "\" character, i.e., "\\". An example is:

scene_path = "g:\\3dsmax25\\scenes" -- specifies file path g:\3dsmax25\scenes

For strings that are used as file names or paths, the "/" character can be used instead of the "\\". MAXScript internally interprets the "/" character as a "\" character when used in a file path name string. An example is:

scene_path = "g:/3dsmax25/scenes" -- specifies file path g:\3dsmax25\scenes

See also

String Values


Time Literals

Time is a basic data type in MAXScript. Its semantics are based on animation time in 3ds max, where you can express time in frames, ticks or normalized time. In 3ds max, time is stored with a resolution of 4800 ticks per second. The format for a time literal is one of:

[-]{<decimal_number>[m | s | f | t]}+ -- minutes/sec/frames/ticks

[-]{<digit>}:{<digit>}[.{<digit>}] -- SMPTE mins:secs.frame

[-]<decimal_number>n -- active segment normalized time

In the first form, the {...}+ indicates one or more repetitions, so you can string together minutes/seconds/frames/ticks. If you do this, they must be in the specific minutes/seconds/frames/ticks order.

The normalized time form is always relative to the current active animation time segment.

Examples

2.5s -- 2.5 seconds

1m15s -- 1 minute 15 seconds

2m30s5f2t -- 2 minutes 30 seconds 5 frames 2 ticks

125f -- 125 frames

18.25f -- 18.25 frames

1f20t -- 1 frame 20 ticks

2:10.0 -- 2 minutes 10 seconds 0 frames (SMPTE)

0:0.29 -- 29 frames (SMPTE)

0.45n -- 0.45 normalized time (fraction of active segment)

See also

Time Values


Pathname Literals

Names identify entities such as variables and parameters inside the running MAXScript program. If you want to identify objects by name in the 3ds max scene, you use a pathname. Pathnames can name a single object in the scene, specify a particular object using a path through the object hierarchy, or name sets of objects using pattern matching.

The full syntax for a pathname literal is:

<path_name> ::= $<path> | $

<path> ::= [ <objectset> ] [ / ] [ <levels> ] <level_name>

<levels> ::= <level> { / <level> }

<level> ::= <level_name>

...

<level_name> ::= { <alphanumeric > | _ | * | ? | \ }

'{ <alphanumeric > | _ | * | ? | \ }'

The root of a <path> can be an <objectset>, which limits the pathname searching to the object set you specify. ObjectSets are described in ObjectSet Values.

Examples:

$box01 -- object named 'box01'

$torso/left_up_arm/left_low_arm -- hierarchy path name

$*box* -- all objects with 'box' in

-- the name

$torso/* -- all the direct children of

-- $torso

$helpers/d* -- all helper objects whose name

-- starts with 'd'

All objects in a 3ds max scene are arranged in a hierarchy as presented in Track View. This is both an important organizing scheme in 3ds max, and it suggests a MAXScript naming scheme for objects based on the path to an object through the hierarchy. It is also very similar to path names in an operating system's directory structure. For example,

$dummy/head/neck

names the scene object neck whose parent is object head, which has the top-level parent object dummy. This pathname helps you identify a specific object in a 3ds max scene, even if several objects have the same name. If head is unique in the scene, MAXScript lets you use the shorthand $head to refer to it regardless of its hierarchy position. Even if the object is not uniquely named you can use the shorthand form, but it is undetermined which of the same-named objects you will get.

Pathnames also provide a powerful way to refer to several objects at once, such as all the children of a certain parent, or all the objects with names containing the string foot. For this, you can use wild-card patterns, as you can with operating system shell file naming schemes. For example,

$dummy/*

names all the immediate children of dummy. The "*" character is used as a wild card. Or,

$neck*

finds all the objects, whose names start with the string neck, anywhere in the hierarchy.

You can use wild cards anywhere in a pathname. For example,

$*foot*

finds all the objects with foot anywhere in their names. The "*" wild-card character effectively matches any number other characters.

You can also use the "?" wild-card character to match exactly one "don't care" character. This is, the "?" wild-card character will match any single character. For example,

$box0?

finds all the objects that begin with box0 and have exactly one character after the 0 in their names.

Wild-card characters can also be used for specifying parent levels in a hierarchy. For example,

$dummy/*/*

names all the children of all the children of $dummy.

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 Collections.

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

ObjectSet Values

Collections


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 String Literals 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 Point2 Values and Point3 Values. You can write point literals using the following forms:

2D

[ <expr>, <expr> ]

3D

[ <expr>, <expr>, <expr> ]

where <expr> evaluates to an Integer or Float value.

Examples:

[320, 240] -- 2D point

[10, 20, 30] -- 3D point

Expressions in a literal are evaluated when the literal is built. The following script and results show the value stored in a Point3 when expressions are used in the literal:

Script:

a=10

b=45

[10, 20, 30]

[sin a, 2 * b, a^2 + b^2] -- can contain expressions

Output

10.0 -- result of line 1

45 -- result of line 2

[10,20,30] -- result of line 3

[0.173648,90,2125] -- result of line 4

See also

Point2 Values

Point3 Values


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 Array Values. Array literals can be expressed in two forms:

#( <expr> { , <expr> } )

#() -- empty array

Examples:

#(1, 2, 3)

#()

#(1,"foo",#(1.2, -4,#fred),[1,2,3]) -- this one has a nested array

Expressions in an array literal are evaluated when the literal is built. The following script and results show the values stored in an array when expressions are used in the literal:

Script:

a=10

x=45

#(1, sin x, a * 2.3) -- can contain expressions

Output:

10.0

45

#(1, 0.707107, 23.0)


Expressions

MAXScript is an expression-based language. Every construct in the language is an expression and yields a result; this includes constructs that other languages consider statements. The simplified syntax of the language allows you to build very expressive code. Anywhere you can write an <expr> expression, you can write any construct in MAXScript.

A good example of this is the if construct. In statement-based languages, there is usually one syntax for if statements and another for conditional expressions. In MAXScript, a single syntax is used for both cases. For example, the following two lines of code are both valid, and their meaning should be obvious:

if a > b then print c else print d

x = if a > b then c else d

You can also write the following line, containing a nested if expression and a nested assignment, which itself is an expression:

x = if (if a > b then c else d) < e then f else (g = 23)

Another example is the block-expression, denoted <block_expr>. It contains a series of <expr> expressions enclosed in parentheses:

(

print a

print b

if a > b then print "the big a"

)

Each expression in the block is separated by a line break. You can also write several expressions on one line using a ";" (semicolon) to separate them:

(print a; print b; if a > b then print "the big a")

Block-expressions are themselves <expr> expressions. They evaluate their component expressions in sequence and yield as their value the value of the last expression in the block.

To create classic block-structured statements, you might write:

if a > b then

(

print c

x = sqrt (c)

)

else

(

print d

x = sin (e)

)

or, use a nested block-expression to compute a comparison operand:

if a > (y = sin b; sqrt(y * z)) then print c

At its simplest, a MAXScript program is made up of <expr> expressions. An <expr> is defined as any of the following:

<simple_expr>

<variable_decls>

<assignment>

<context_expr>

<if_expr>

<while_loop>

<do_loop>

<for_loop>

<loop_exit>

<case_expr>

<try_expr>

<function_def>

<function_return>

<struct_def>

<max_command>

<utility_def>

<rollout_def>

<tool_def>

<rcmenu_def>

<plugin_def>

This list of expressions constitute the main constructs in MAXScript.

See also

Simple Expressions

Context Expressions

Controlling Program Flow

Creating Functions

Structure Definition

Literal Constants

Variables – Assignment and Scope

3ds max Commands

Scripted Utilities

Utility Clauses

Scripted Mouse Tools

Scripted Right-Click Menus

Scripted Plug-ins


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

Math Expressions

Comparison Expressions

Logical Expressions

Function Calls

Block-Expressions


Operands

Operands, denoted as <operand> in the syntax definitions, are the references to values that surround operators or are passed as parameters to a function. Prime examples are Literal Constants and variable names. Operands are divided into two groups, Factors and Accessors.

Factors

Factors, denoted as <factor> in the syntax definitions, are references to values, where the entire value is acted on. A factor can be a Literal Constants, a Reserved Global Variable, a variable name, or an expression.

The unary minus applies the math negate operator to its operand.

-<operand> -- unary minus

The unary minus is only applicable to factors that evaluate to a number.

Examples:

-0.75

sin (-a*pi)

Accessors

Accessors are constructs that let you access the components in compound values, such as arrays and 3D points. There are two kinds of accessors corresponding to the two kinds of compound values in MAXScript:

  • The component values are arranged in an indexable sequence, as in arrays or strings.

  • The compound value contains a fixed set of named components, as with 3D points and time intervals.

All 3ds max objects, such as boxes, spheres, bend modifiers, or bitmap textures are treated as compound values in this sense. All of their parameters, such as height and angle, or map file name, are accessed as named components. In MAXScript, these named components are referred to as properties.

Accessors have one of two forms, an <array_index>:

<operand> [ <expr> ] -- an indexed element

or a <property>:

<operand>.<var_name> -- a named property

Examples

maps[i]

selection[n+1]

position.x

bend.angle


Math Expressions

The math expressions in MAXScript correspond to the common operator expressions in mathematics, such as add, subtract, multiply, divide, and so on. The <math_expr> constructs in MAXScript are:

<math_operand> + <math_operand> -- standard arithmetic addition

<math_operand> - <math_operand> -- standard arithmetic subtraction

<math_operand> * <math_operand> -- standard arithmetic

-- multiplication

<math_operand> / <math_operand> -- standard arithmetic division

<math_operand> ^ <math_operand> -- exponential, raise to the power

<math_operand> as <class> -- conversion between types

where <math_operand> can be one of:

<operand>

<function_call>

<math_expr>

Note that a math operand can be another nested math expression. This is another instance of a recursive syntax definition which lets you create arbitrary sequences of operands and operators. Note also that the math unary minus is not defined here, it is one of the <operand> types described in Operands.

Examples

42

2 + 2

2 * a - sin x / b -- using a function call

(a + b) * -c

2 ^ n

(n + 1) as string -- converts result to a string value

The conversion operator, as, works between selected sets of source and destination value types. Only certain kinds of values can be converted into certain other kinds of values. These allowed conversions are defined for each type of value, and are documented with the value type descriptions.

See also

Math Assignment

Precedence and Association Rules

Polymorphism


Math Assignment

MAXScript provides the C language shorthand form of assignment that can be used to modify a value in place, as shown in the following long-form examples:

x = x + 1 -- increment x by one

$obj.pos = $obj.pos * scale -- multiply $obj.pos by scale

Corresponding to the four math operations (+, -, *, and /) are assignment operators that apply the operation to the assignment's destination and update the destination with the result. Their syntax is:

<destination> += <expr> -- add <expr> to destination

<destination> -= <expr> -- subtract <expr> from destination

<destination> *= <expr> -- multiply destination by <expr>

<destination> /= <expr> -- divide destination by <expr>

Using the shorthand form of assignment, the previous examples can be written as:

x += 1 -- increment x by one

$obj.pos *= scale -- multiply $obj.pos by scale


Precedence and Association Rules

As in mathematics, a sequence of operands and operators is evaluated according to a set of precedence and association rules. The following table shows sample expressions and their order of evaluation:

Expression Order of evaluation

a + b * c a + (b * c)

a + b - c (a + b) - c

a ^ b ^ c a ^ (b ^ c) -- exponentiation, raise to the power

The evaluation order in the previous table follows standard precedence rules, where * and / operations are evaluated before + and - operations, and where + and - operations associate to the left (that is, operands on the left are evaluated before operands on the right) and exponentiation operations associate to the right (that is, operands on the right are evaluated before operands on the left).

These precedence rules define the ordering of evaluation in all expressions in MAXScript, unless parenthesizing is used to force a different order. Expressions in parenthesis are evaluated before the surrounding operands are applied.

The following list shows the precedence order for math expressions starting with the highest precedence:

<operand>

<function_call>

as

^ -- right associative

* and / -- left associative

+ and - -- left associative

See also

Function Precedence


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

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


Comparison Expressions

Using comparison expressions you can compare values of comparable types. The result is always one of the two Boolean values, true or false. The various forms of <compare_expr> are as follows:

<compare_operand> == <compare_operand> -- equal

<compare_operand> != <compare_operand> -- not equal

<compare_operand> > <compare_operand> -- greater than

<compare_operand> < <compare_operand> -- less than

<compare_operand> >= <compare_operand> -- greater than or equal

<compare_operand> <= <compare_operand> -- less than or equal

where <compare_operand> can be one of:

<math_expr>

<operand>

<function_call>

Examples:

a > b

sin x == 0.0

a + b <= n - 1

Comparison operations have lower precedence than math operations. In the previous examples, the sin function call and the "+" and "-" operations are performed before the comparisons.

As with math expressions, the comparison operators work on all appropriate types. Equal "==" and not-equal "!=" operate on all types, and the relative comparisons work between comparable types. The allowable comparison operators are documented with the value type descriptions.


Logical Expressions

Logical expressions combine the results of Boolean expressions, such as comparisons, to construct complex conditional expressions. The forms of a <logical_expr> are as follows:

<logical_operand> or <logical_operand> -- true if either operand

-- is true

<logical_operand> and <logical_operand> -- true if both operands

-- are true

[ not ] <logical_operand> -- true if operand is false

where <logical_operand> is one of the following:

<operand>

<compare_expr>

<function_call>

<logical_expr>

Logical operators only operate on Boolean values, so each <logical_operand> must evaluate to true or false.

Examples:

a > 0 and a < n + 1

not x and y

a and b or c and d and not e

As with math expressions, <logical_expr> is a recursive definition, meaning a logical operand can be another logical expression. You can have arbitrary sequences containing and, or, and not, and the order of evaluation is defined by the following precedence ordering (in decreasing order of precedence):

not -- right associative

and -- left associative

or -- left associative

This means that in an unparenthesised logical expression, not is evaluated before and which is evaluated before or.

Logical operators have a lower precedence than comparison operators, math, and function calls. Therefore, these operations are always evaluated before logical operators, which follows convention. The previous examples would be evaluated in the following order:

(a > 0) and (a < (n + 1))

(not x) and y

(a and b) or ((c and d) and (not e))

See also

Short-Circuiting Logical Expressions


Short-Circuiting Logical Expressions

Following the convention in most other programming languages, logical expressions in MAXScript are short-circuiting or non-strict. This means only enough of the sub-expression is evaluated to determine the overall result:

  • If the first operand is false in an and expression, the result must be false, therefore, the second operand is not evaluated.

  • If the first operand is true in an or expression, the result must be true, therefore, the second operand is not evaluated.

This saves execution time and enables useful shorthand notation. For example, if you want to calculate "sin a" if the value of variable a isn't undefined, you can use the following example:

if a != undefined and sin a > 0 then ...

In a strict language, the "sin a" evaluation of an undefined operand results in an error, and you would need to break up the expression into two if statements:

if a != undefined then

if sin a > 0 then ...


Function Calls

A function call expression passes an optional list of arguments to a MAXScript or user-defined function, and the value returned by the function is the function call expression's result. A <function_call> has one of the following forms:

<operand> { <argument> }+ -- one or more arguments

<operand> () -- no arguments

in which, <argument> is one of the following:

<operand>

<name>: <operand> -- keyword argument

Examples:

sin a

tan2 x y

print (n + 1) to:debug

fns[i] $box01 -- get function out of array fns

move object1 [10,20,x * 3]

This syntax is unlike most programming languages which typically use parenthesized lists of comma-separated arguments. This syntax was chosen for MAXScript for the following reasons:

  • It is simpler and easier to use, particularly if a function has many optional keyword arguments.

  • The language is used in a command-line window within 3ds max. Therefore this form is similar to other command or shell languages that users might be already know.

All 3ds max objects, including geometric objects, splines, materials, and so on are created using function calls. The name of the object creation function is the object's class name. For example:

standard() -- create a standard material

bend angle:45 -- create a bend modifier

box height:20 width:40 -- create a box

See also

Positional and Keyword Arguments

Function Precedence

Code Layout

Special Notes about Function Calls

Creating Functions


Positional and Keyword Arguments

A function can take two kinds of arguments:

  • Positional Arguments. If you call a function that takes positional arguments, you must specify those arguments first and in the correct order. Positional arguments correspond to the function arguments in most programming languages—they are required and have a fixed number and order.

  • Keyword Arguments. You write keyword arguments as a keyword:value pair, and they can appear in any order after the positional arguments. Functions can use some or all of their keyword arguments as optional arguments. If you call a function and don't supply optional keyword arguments, they will have either the default value supplied by the called function, or the special value unsupplied when first referenced in the called function.

Optional keyword arguments are useful in command languages where commands can have many options. They are particularly useful within 3ds max where most functions have numerous optional keyword arguments. For example, all scene object creation functions take optional keyword arguments for their creation parameters. As there are sometimes more than 100 arguments to these functions, using positional arguments would simply be unworkable.

As an example of positional arguments, the syntax for the print function is:

print <value> [ to: <file> ]

<value> is a positional argument, and is required. to: <file> is an optional keyword argument, where to is the argument keyword and <file> is the argument value. If the to argument value is unsupplied, MAXScript outputs <value> to Listener. Otherwise, MAXScript outputs <value> to the file specified by <file>.

As another example, you can create a sphere object in the 3ds max scene with no arguments:

sphere()

Or, you could specify just one argument:

sphere radius:23

Or, you can specify more optional arguments:

sphere segs:20 smooth:on radius:15 hemisphere:0.5 mapcoords:on

For those keyword arguments not specified when creating 3ds max objects, default values are used. The default value used for each keyword argument is shown in the descriptions of the object classes.


Function Precedence

A <function_call> has a lower precedence than an <operand>, but it has a higher precedence than all the math, comparison, and logical operations. This means you have to be careful about correctly parenthesizing function arguments.

For example:

sin x + 1

is evaluated as:

(sin x) + 1

In general, you have to put arguments that are expressions inside parentheses, as in:

sin (x + 1)

atan2 (y - 1) (z - 1)

This rule has one exception, the unary minus. It is recognized as one type of <operand> you don't have to parenthesize. For example:

sin -x

is interpreted as:

sin (-x)


Code Layout

The end-of-line layout rules, as described in Source Code Layout and Continuation Lines, mean an end-of-line indicates the end of a function call if the line ends at the end of a complete argument.

You cannot simply break up a function call with many arguments into several lines, because each line becomes a separate expression, almost certainly causing an error. Use the "\" continuation character in this situation:

foo = standardMaterial twosided:on shininess:34 \

diffuseMap:baz \

opacityMap:bar \

bumpMap:boo


Special Notes About Function Calls

Functions in MAXScript are just another value that can be stored in variables and arrays, and passed to other functions as arguments. Such functions are sometimes called higher-order functions. All built-in functions, and functions that MAXScript defines based on the 3ds max object classes, are values stored in system global variables of the same name as the function. When you define a scripted function, the function value is placed in a variable with the same name as the function. You can use the value in these variables and work with them as you would with other values, such as storing them in an array or passing them as arguments.

Because the function name is a variable that simply yields the function itself, functions that take no arguments need to be called in a special way. For example, if you want to call a function get_current_target that takes no arguments, you can not simply write:

t = get_current_target

This stores the get_current_target function value in variable t, rather than storing the result of executing function get_current_target. Instead, you must use the "()" nullary call operator:

t = get_current_target()

The function to be called is defined as an <operand> in the syntax for function calls. This means that it can be an expression that is evaluated to get the function to call. For example:

(if a > b then sin else cos) x -- conditional function choice

handlers[x] $box01 [1,1,1] -- get the function out of an array


Block-Expressions

Block-expressions are the basic constructors for structured code. They allow you to group a sequence of expressions and evaluate them in sequence as though they were a single expression. The syntax for <block_expr> is:

( <expr> { (; | <eol>) <expr> } )

That is, a parenthesized sequence of expressions with each <expr> separated by either a line break or a ";" semicolon.

MAXScript also allows empty block-expressions, (). This is useful when incrementally building code in order to place an empty expression in a path to be filled in later. When evaluated, empty expressions yield the value undefined.

Examples:

(

d = centre.x^2 - (p.x^2 + p.y^2)

newz = if d > 0 then sqrt d else p.z

print newz

)

if x < y then (print x; print y; u += 10; print u)

You can use a mixture of line breaks or semicolons:

(

print x; print y

u += 10

print u; print z

)

Because a block-expression is an <operand>, you can insert a block-expression anywhere you can put an <operand>. This is unlike most languages which limit where you can put blocks of code to only a few places. Further, because all constructs are expressions in MAXScript, a block-expression yields a value defined to be the last <expr> in the block. This allows you to use a nested sequence of expressions to compute an operand for some operation:

$box.pos.z =

(

d = x^2 - y^2

if d > 0 then sqrt d else z

)

Here, the result of the block-expression is the result of the final if expression, which is then assigned to $box.pos.z.

Because the item in parentheses can be any <expr>, you can turn any construct in MAXScript into an operand by putting it in parentheses. This allows you to write the following example, in which the operand to be indexed is the conditional result of an if expression:

(if a > b then c else d)[n + 1]

As described in Scope of Variables, top-level open parentheses in a script file or in the Listener create a new variable scope. Any block-expressions with the top-level block-expression do not create a new variable scope, even if the variable is explicitly declared as local in the inner block-expression. A variable's scope extends into any block-expressions within the variable's scope. If you declare a variable as local in a scope, the newly declared local variable hides any outer variables with the same name. Any reference to that variable name later in the local variable's scope refers to the new local variable. At the end of the local variable's scope, the next outer variable becomes visible again. This is shown in the following script:

Script:

a=1

(

local a=2

(

local a=3

)

print a

)

a

Output:

1 -- result of line 1

3 -- output of line 7

3 -- result of block-expression lines 2 to 8

1 -- result of line 9

Any variable names used in a block-expression which have not been created at a higher scope level are implicitly declared as local in the present scope. This can result in unexpected execution results for scripts that are not set up correctly. For example, consider the following script:

(b=bend();addmodifier Objs b) -- create bend modifier and apply to objects

b.angle=10

The first time you execute this script, the following error message is generated:

-- Unknown property: "angle" in undefined

If you execute the script again, it works properly. The reason is there are actually two variables with the name b – one is local to the block-expression and contains the bend modifier value, and the other is global and has the value undefined. During the second execution, global b exists, so the block-expression does not implicitly declare a new variable b, rather it uses the global variable b.

When writing scripts, it is also a good programming practice to explicitly declare as local all variables unless you really want them to be global variables. There are several reasons for this practice:

  • All the variable names used in the block or function will be together, which makes it easier to find the variable names and helps prevent using incorrect names in the script.

  • If more than one script is executing at the same time (for example, you are running a scripted utility and have a scripted controller in the scene) and both scripts use the same global variable name, the two scripts can interfere with one another. This can cause apparently random failures of one or both scripts.

  • You are sure you are using the correct variable in the event that a variable with the same name has already been declared at a higher scope, and you won't inadvertently change the higher-level variable's value.

  • Values of variables explicitly defined as local are displayed in error call stack trace-backs.

  • In 3ds max R2.5, if a 3ds max class, a MAXScript method, or a MAXScript read-only global variable has the same name as an implicitly declared local variable, a MAXScript runtime error will be generated if an assignment to that variable name occurs. Since the variable name already existed with a global scope, an implicitly declared local variable was not created. Since one or more new 3ds max classes will be created by any third party plug-ins the user has loaded, you were not be able to tell ahead of time if a variable name was a global variable name. In 3ds max 4, if the MAXScript compiler detects that the first reference to such a variable is an assignment, it will implicitly declare a local variable, rather than leaving it as a reference to a read-only system global. For example, executing the following expression in 3ds max R2.5 would result in a value of Box, since Box is a 3ds max object class. In 3ds max 4, MAXScript detects that the first use of variable box is an assignment and creates an implicitly declared local variable box. The result of this expression in 3ds max 4 is the value undefined.

(if false do box=10;box)


Context Expressions

Context expressions are the parts of the MAXScript syntax that are most specifically designed for use with 3ds max. Context expressions are mirrors of some of the most important abstractions in the 3ds max user interface - the animate button, the time-line slider, the working coordinate system, and so on. Context expressions make it as easy to create animation and perform geometry manipulation in MAXScript as these tools do in the user interface.

The basic idea for this is a prefix is supplied that sets up a context for the evaluation of its expression. For example:

animate on

(

move $box01 [20, 0, 0]

rotate $box02 45 x_axis

)

This effectively "turns on" the animate button for the duration of its block-expression. The move and rotate will automatically generate keyframes, just as would happen if you turned the animate button on in the 3ds max user interface and moved objects around. Another kind of context expression has a prefix for setting the current animation time, as though you had moved the time slider. If we mix the two forms together, like this:

animate on

(

at time 0 $box01.position = [-100, 0, 0]

at time 100 $box01.position = [100, 0, 0]

)

you can see how to do keyframe animation in MAXScript.

The full syntax for <context_expr> is:

<context> { , <context> } <expr>

where <context> is one of:

[ with ] animate <boolean>

at level <node>

in <node>

at time <time>

[ in ] coordsys <coordsys>

about <center_spec>

[ with ] undo <boolean>

Examples:

-- randomly jiggle each object in the selection around + or - 20 units

in coordsys local selection.pos = random [-20,20,20] [20,20,20]

-- rotate all the boxes 30 degrees about the y_axis of $foo

about $foo rotate $box* 30 y_axis

-- generate a keyframed animation of $foo randomly chasing $baz

animate on

for t in 0 to 100 by 5 do

at time t

foo.pos = $baz.pos + random [-10,-10,-10] [10,10,10]

The individual context expressions are described in the following topics:

animate

at level, in

at time

coordsys

about

undo

See also

Cascading Contexts

Nested Contexts

Sticky Contexts


animate

The [ with ] animate <boolean_expr> context corresponds to setting the Animate button in the 3ds max user interface. Placing an expression, operation, or block-expression within an animate on context causes keyframes to be generated whenever an animatable property of a 3ds max object is changed, regardless of the actual state of the Animate button. Likewise, placing an expression within an animate off context prevents keyframes from being generated whenever an animatable property of a 3ds max object is changed. Expressions that change an animatable property of a 3ds max object, and are not within an animate context, will generate keyframes only if the Animate button is on.

Setting the animate context on or off does not affect the state of the Animate button. The state of the Animate button can be queried and set using the animButtonState global variable. The user can be prevented from changing the state of the Animate button using the animButtonEnabled global variable.

Examples:

loadheight=obj.pos.z

-- lift object, no key generated

animate off

obj.pos.z=loadheight+LiftHeight

-- Create key at time tStart to keep object lifted until that time.

-- If tStart != 0, a key will also automatically be created at frame 0.

-- Then create a key at time tEnd to drop the object

with animate on

(

at time tStart obj.pos.z=loadheight+LiftHeight

at time tEnd obj.pos.z=loadheight

)


at level; in

at level, in

The at level <node> and in <node> contexts set the specified node to be the effective root for any pathnames specified, or scene objects created, in the context. These contexts automatically prefix the specified node to any pathnames in the context. They also set the specified node to be the parent for any scene objects created in the context.

To be able to use pathnames within level contexts to name objects anywhere in the scene, you can override the current working level by using a rooted pathname. A rooted pathname has an extra "/" before the first-level name and indicates "start at the actual root of the object tree". For example:

scale $/baz/* [1,1,2]

operates on the object baz in the actual top level, not just as a child of the current working level.

You can also use this rooted pathname form to force a pathname to only consider top-level objects when you name a single object. For example

$foo

looks throughout the whole scene, at all levels for an object named foo, but,

$/foo

will only look for a top-level object named foo.

Examples:

in $mannequin01...LClav...hand -- set context to hand

$mannequin01.spine.LClav.arm.hand

(

rotate $thumb1 15 y_axis -- rotate hand's child

-- thumb

rotate $finger11 10 y_axis -- rotate hand's child

-- first finger

PalmCenter=$finger21.parent.pos -- get hand's position

PalmCenter+=(LHandPos-$finger21.pos)/2. -- calculate center of

-- palm

dummy name:"palmLink" pos:PalmCenter -- create a dummy there,

-- dummy is a child of

-- the hand

)

in $dummy

(

sphere name:"ear1" pos:[10,10,10] -- create automatically as

-- children of $dummy

sphere name:"ear2" pos:[-10,10,10]

scale $foo/* [1,1,2] -- look for 'foo' as a child

-- of $dummy

)


at time

The at time <time> context corresponds to the 3ds max time slider. Any animatable property references will yield their interpolated values for the specified time. If the Animate button is on, or the script is also in an animate on context, keyframes are generated at the specified time when an animatable property of a 3ds max object is changed.

Setting an at time context does not affect the 3ds max time slider. The time associated with the time slider can be queried and set using the sliderTime global variable.

Examples:

-- generate a keyframed animation of $foo randomly chasing $baz

animate on

for t in 0 to 100 by 5 do

at time t

$foo.pos = $baz.pos + random [-10,-10,-10] [10,10,10]


coordsys

The [ in ] coordsys <coordsys_spec> context corresponds to the current reference coordinate system list in the main 3ds max toolbar. Prefixing an expression, operation, or block-expression with a coordsys context causes 3D coordinate operations to be interpreted in the specified coordinate system. Moving, scaling, or rotating objects, or setting transform-related properties within a coordsys context operate in relation to the given coordsys. Accessing coordinate properties such as position, center, rotation axis, and so on, within a coordsys context causes those values to be delivered relative to the given coordsys.

The following forms are supported:

[ in ] coordsys world

use the world space coordinate system

[ in ] coordsys local

use the object's local coordinate system

[ in ] coordsys parent

use the object's parent's coordinate system

[ in ] coordsys grid

use the active grid's coordinate system

[ in ] coordsys screen

use the currently active viewport's coordinate system

[ in ] coordsys <node>

use the specified node's local coordinate system - this is equivalent to the "pick" coordinate system capability in the 3ds max user interface

[ in ] coordsys <matrix3>

use the coordinate system specified by the given 3D matrix

Examples:

-- randomly jiggle each object in the selection around +/- 20 units

in coordsys local selection.pos = random [-20,20,20] [20,20,20]

-- rotate objects in parent's coordinate system

in coordsys parent rotate selection (EulerAngles 0 0 90)


about

The about <center_spec> context is the MAXScript equivalent of the rotate/scale transform center list on the main 3ds max toolbar. It defines the center point about which any scale or rotation operation is performed within its context. Note that, like the center list in 3ds max, this sets only the center point for the operation, not the axis. The axis is taken from the current working coordinate system set using the coordsys context expression:

about selection

rotates/scales about the center of the current selection

about pivot

rotates/scales about each object's pivot point

about coordsys

rotates/scales about the center of the current working coordinate system set using the coordsys context expression

about <node>

rotates/scales about the pivot point of the given object

about <matrix3>

rotates/scales about the center of the coordinate system specified by the given 3D matrix

about <point3>

rotates/scales about the given point with coordinate system and axes taken from the current working coordinate system.

Examples:

-- rotate all the boxes 30 degrees about the y_axis of $foo

about $foo rotate $box* 30 y_axis

-- rotate each planet 45 degrees around its parent

in coordsys parent about coordsys rotate $planets* 45 z_axis


undo

The undo <boolean> context provides control over whether scripted scene changes will be undoable. By default, the operations performed in MAXScript are undoable. This means that scene-modifying commands typed in the Listener are undoable by default. Making this a context-controlled activity allows you to decide when the undo overhead is to be taken.

Example:

undo on

(

delete $box*

delete $sphere*

clearUndoBuffer()

)

The undoable operations appear as items labeled "MAXScript" in the 3ds max Undo menu. It is important to note that the granularity of the undoable operations is at the level of entire undo clauses. In the previous example, one entry is added to the Undo stack containing both deletes as a single operation. Choosing undo for this entry in the Undo menu causes both deletes to be undone. Therefore, you can control the granularity of an undo by choosing the appropriate undo block expression groupings.

You can invoke an undo from MAXScript with the max command:

max undo

When you script very large scene changes, you should consider turning undo off as it is quite easy to fill up the Undo stack and consume substantial amounts of memory. Disabling undo can improve performance in this situation. If the actions your script performs could interfere with entries already in the Undo stack, you should explicitly clear the Undo stack before enabling undo. An entry in the Undo stack generally expects the scene to be in the state it was when the entry was placed in the Undo stack. If you interrupt the storing of Undo stack entries, and modify the scene in an incompatible way (such as deleting an object that an entry assumes is still around), a 3ds max crash is likely if you then try to perform an undo.

Using the following functions you can control the undo and scene save states in 3ds max:

clearUndoBuffer()

empties the Undo stack, both providing a way to reset the undo state and another way to control the save-changes requester.

setSaveRequired <boolean>

lets you set the 3ds max system "dirty" flag. If this flag is set or there are entries in the Undo stack, you are asked if you want to save the scene file on a File > New or File > Reset.

getSaveRequired()

returns true if the 3ds max system "dirty" flag is set to true or if the Undo buffer is not empty. If the Undo buffer if not empty, this function will still return true, even if you just called setSaveRequired false.

Normally, if there are entries in the Undo stack when the scene is closed, 3ds max will prompt with a save-changes requester. In some cases, where you are controlling undo in MAXScript, you may want to force the need for a save-changes prompt.


Cascading Contexts

You can cascade a set of context prefixes, optionally separated by commas, onto one subject expression, effectively applying all the contexts (in order) to the subject expression. For example:

animate on, at time (t+1), with undo off, coordsys local

(

...

)

All the context forms are true expressions, yielding the value of their subject expression, so:

pos0 = at time 35 $box01.position

pos1 = at time 75 $box01.position

assigns the box01 position at time's 35 and 75 to variables pos0 and pos1. This is particularly useful with the at time context, as you can very easily do across-time computations. The operand to an at time context can be any valid time value (numbers are taken as frames for convenience), including sub-frame times down to the tick level. The animation system in 3ds max will interpolate animated parameters at these fine levels so you can easily do sub-frame simulation computations.


Nested Contexts

All context expressions remember the prior setting of the context when they are set, and restore the original setting when the expression completes. Therefore, you can nest context clauses in any way you want, including contexts of the same type to override an outer setting.

Example:

with animate on, at time t

(

move ... -- all these place keys

rotate ...

animate off -- turn off animate for a bit

(

move ... -- working maneuvers, these don't effect animation

rotate ...

) -- animate on is restored here

scale ... -- place keys again

...

)

Further, all the contexts are dynamically scoped. Any code inside a context expression, any functions that code calls, and functions they call down to any level, are executed in the current prevailing context. So, a function can move an object and place keyframes at a certain time when called from one client and do no keyframing when called from another client, depending on how the callers have set up the contexts. Of course, the called function can explicitly set its own contexts if it wants to, overriding those that may have been set up by the caller.


Sticky Contexts

You can force the settings of contexts such as coordsys, animate, time, and so on, to be "sticky." The settings will stay active for any code execution that follows, up until the point you change them or override them with a context prefix for an expression. This is particularly useful when working in the Listener, allowing you to set a context and then perform several interactive operations in that context without prefixing each with the desired context construct. Establishing a sticky context is accomplished with the set construct:

set <context>

where <context> is one of the MAXScript context prefixes: animate, time, in, coordsys, about, level, or undo.

Example:

set animate on

set time 30f

move $foo [80,0,0]

scale $baz [1,1,3]

$bar.bend.angle += 23

...

set animate off

set time off

This turns animate on and sets the current time to frame 30 after which any number of interactive operations can be performed that will generate animation at frame 30. The modes are then returned to default. As shown in this example, certain the MAXScript contexts permit syntactic variants to make the set construct read clearly. In particular, these are:

set time <value> | off -- variant of at time <time>

set level <node> -- variant of at level <node>

The time context can be set to off, signifying the current value of the 3ds max time slider is to be used.

All the set constructs are expressions that yield the context setting that was in force at the time the new context was set. This allows you to simulate the standard nested forms of these constructs by storing the old context in a variable and using that to restore the context later. For example:

oc = set coordsys parent -- remember old coordsys

rotate $foo (quat 30 z_axis)

...

set coordsys oc -- restore it

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.


Controlling Program Flow

MAXScript has several <expr> expression forms used to explicitly control the flow of execution. They are:

<if_expr>

<case_expr>

<do_loop>

<while_loop>

<for_loop>

<loop_exit>

<try_expr>

These expression forms correspond to the standard control constructs found in many programming languages. Each is described in its own topic:

If Expression

Case Expression

While and Do Loops

For Loop

Loop Exit

Try Expression

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 Change Handlers and When Constructs 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 Utility and Rollout Properties, Methods, and Event Handlers for more information.


If Expression

The if expression is used to conditionally execute an expression based on the result of a boolean test expression. The syntax for an <if_expr> is one of:

if <expr> then <expr> [else <expr> ]

if <expr> do <expr>

Examples

if a > b do (print d; print e)

a = (if d == 0 then 0 else a / d)

The first <expr> is a test expression that must evaluate to true or false, such as a comparison or logical expression. If the result is true, the then or do <expr> is evaluated and its value is returned as the result of the <if_expr>. If the result is false, the optional else <expr> is evaluated and its value is returned as the result of the <if_expr>. If there is no else or the do form is used, the <if_expr> returns the value undefined.

The do form is provided particularly for use during interactive sessions in the MAXScript Listener. When you enter expressions for immediate evaluation into the Listener, MAXScript determines if your expression is complete and then evaluates it. If you use the optional else form in the Listener and you want to omit the else <expr>, MAXScript continues to "wait and see" if you enter an else <expr>. The line break after the then <expr> is legal and does not cause MAXScript to evaluate the current line right away. As an example, if the following script is entered in Listener, the first line will not evaluate until you enter the second line:

if match x y then print x

print "hello"

When you use the optional else form inside a block or another expression, MAXScript can determine from the code that follows it if you omitted the optional else. Use the do form for if statements without an else as top-level commands in the Listener:

if match x y do print x

As described in Expressions, 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

The case expression is used to select an expression to be evaluated from a set of labeled expressions based on a test value compared against the labels.

Only the first expression whose label matches the test expression is evaluated. All labels must be comparable to the test expression. Labeled expressions can be block-expressions, so you can use the case expression as a case statement, choosing between blocks of code to execute.

The syntax for <case_expr> is:

case [ <expr> ] of ( <cases> )

where <expr> is the test expression and <cases> is a sequence of labeled expressions:

<factor>: <expr>

default: <expr>

Examples

new_obj = case copy_type.state of

(

2: copy $foo

3: instance $foo

default: reference $foo

)

A special label, default, can be optionally used to tag the expression that will be evaluated if no other labels match the test expression. If the default label is not used, and no label matches the test expression, the case expression returns a value of undefined.

The labels are <factors> - elements such as number literals, name literals, string literals, variables, or block-expressions. When a case expression is evaluated, the test expression is evaluated once, then each label expression is evaluated in order until one is found that compares equally to the test expression value. The expression it labels is then evaluated and this becomes the result of the case expression. No further labels are evaluated or tested.

The test expression is optional. If it is not supplied, the labels are expected to be Boolean values or expressions, and the first label evaluated as true determines the chosen case. In this variant, it is common to use expressions as labels, so be sure to parenthesize them. For example:

case of

(

(a > b): print "a is big"

(b < c): print "b is little"

(c <= d*3): ...

default: ...

)


While and Do Loops

while and do loops are used to repeatedly execute an expression until a test expression evaluates as false. The while loop and do loop are simple variants of one another. The syntax is:

do <expr> while <expr>

while <expr> do <expr>

Both loops repeat the do <expr> as long as the while <expr> evaluates to the value true. The do form evaluates the do <expr> at least once, evaluating the test expression at the end of each loop. The while form evaluates the test expression at the start of each loop and may not loop at all.

Both forms return as their value the result of the do <expr> from the last successful loop iteration. The while form will return the value undefined if the test expression immediately returns false.

Examples

while x > 0 do

( print x

x -= 1

)

while not eof f do print (read_value f)

do

(

exchanged=false

for i=1 to imax do

(

j=i+gap

if (compare array[j] array[i]) do

(swap array[j] array[i]; exchanged=true)

)

)

while exchanged

See also

Skipping Loop Iterations

Loop Exit


For Loop

The for loop iterates through a range of numbers, time values, or a sequenced collection of values, such as an array or object set. The syntax for the for loop is:

for <var_name> ( in | = ) <sequence> ( do | collect ) <expr>

where <var_name> is the name of the loop index variable that holds the loop value, and <sequence> is the source of values for the loop. The <sequence> can be one of the following:

<expr> to <expr> [ by <expr> ] [where <expr> ]

<expr> [ where <expr> ]

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 or ObjectSet, 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, the current selection set, the children of a node, and the stack of modifiers on an object. See also Collections 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 Scope of Variables, 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:

Example:

obj=$box01

avg_pos=[0,0,0]

offset_pos=[100,100,0]

for obj in $* do -- new for loop index variable obj

-- created even though a variable named

-- obj already exists, scope is for loop

( pos=obj.pos-offset_pos -- new variable pos created, scope is for

-- loop offset_pos already exists outside

-- for loop, its value will be used

avg_pos += pos -- avg_pos already exists outside for

-- loop, its value will be used

) -- for loop index since variable obj goes

-- out of scope

avg_pos /= $*.count

See also

Skipping Loop Iterations

Loop Exit


Skipping Loop Iterations

MAXScript provides a continue construct that allows you to jump to the end of a for, do, or while loop body <expr> and resume with the next loop iteration. Its syntax is:

continue

Examples

for i=1 to 8 do (if i == 5 do continue; print i) -- prints 1..4, 6..8

while not eof f do -- read until reach end of file

(

local line=readline f -- read in a line

if line[1] == "-" do continue -- if comment, skip to next line

line1=parser1 line -- call function parser1

processobjs line1 -- call function processobjs

)

If a continue is executed in a for ... collect loop, the expression result for that loop iteration is not collected in the array of body values.

Example

for i=1 to 8 collect (if i == 5 do continue; i) -- returns #(1, 2, 3, 4, 6, 7, 8)


Loop Exit

MAXScript provides an exit construct for breaking out of for, do, and while loops prematurely, even though the loop test expression is still true. This is often useful to simplify the loop test expression, and still use error or other complex termination tests in the body <expr> of the loop. Its syntax is:

exit [with <expr> ]

Example

while x < y do

(

local delta = x - y

if delta <= 0 then exit -- time to bail

$foo.pos.x = compute_x (foo / delta)

x += 0.1

)

The optional with <expr> lets you specify what the overall value of the loop expression should be if the loop exits prematurely. If you don't specify an exit value, the loop returns the value undefined upon exit.

Exiting a for ... do loop using a with <expr> results in a value of OK.

Exiting a for ... collect loop using a with <expr> results in the array of body values collected up to the point of exit.


Try Expression

MAXScript provides simple exception-handling with the try expression, a simplified form of the C++ exception-handling scheme. The try expression lets you bracket a piece of code and catch any runtime errors. This allows you to respond appropriately or take corrective action, rather than let MAXScript halt the execution of your script and print an error message. The syntax for the try expression is:

try <protected_expr> catch <on_err_expr>

The <protected_expr> is executed and any errors that occur are trapped and the <on_err_expr> is executed. If the <protected_expr> is a block-expression, the block-expression stops executing at the point of the error. If there are no errors in the protected expression, the <on_err_expr> is not executed. This is a very simple error-trapping scheme, but limited heavily by the fact that you cannot get at any error codes or information about the error that occurred.

Example

f = openFile "foo.dat"

try

while not eof f do read_some_data f

catch

(

messageBox "bad data in foo.dat"

results = undefined

)

close f

In this example, any errors in reading or processing the data in the read_some_data() function are trapped, then a Message box is displayed and some clean-up is done. This is a good example of a use for the simple error-trapping.

There is also an associated function, throw(), which can be used to generate your own runtime error and pass on an error you caught when doing some interim clean-up, or do a non-local jump. It has the form:

throw <error_message_string> [ <value> ]

throw()

If you have no intervening catches in your script, calling throw() with error message arguments will cause a runtime error to be signaled and MAXScript will report the error message using its standard error reporting. The optional second argument can be any value you want printed with the error message, perhaps the object involved in the error. This second argument can not be specified if the throw is in the body of a catch() and will generate a compile error if present.

If the try/catch is within another try expression, calling throw() will cause the catch expression associated with the outer try expression to be executed. If you have no intervening catches in your script, calling throw() will cause MAXScript to continue running the script from just after the top-most set of parenthesis surrounding the try/catch, or will stop the currently running script if there are no parenthesis surrounding the try/catch.

If you want to catch an error, perhaps to do some clean-up processing, and then pass the error on to outer handlers or MAXScript for error reporting, you can call throw() with no arguments. This throws the current error again and must only be done inside a catch expression. For example:

Example:

try

(

i=10

try ( i.x=1 ) -- will generate a run-time error

catch

(

print "Bad Error" -- error message printed

try (i.pos=[0,0,0]) -- will also generate a run-time error

catch (throw()) -- throw() will cause outer catch

-- to execute

)

)

catch (print "Really Bad Error Occurred") -- error message printed


Creating Functions

Functions are defined in MAXScript using the function definition expression. The syntax for <function_def> is:

[mapped] (function | fn) <name> { <parameter> } = <expr>

in which <name> is the name of the function. The optional sequence of <parameter>s can be one of:

<name>

<name>: [ <operand> ] -- keyword parameter with

-- optional default value

and the <expr> after the '=' (equal sign) is the body of the function.

The function <name> is actually used to name a variable into which a value representing the function is placed. When you call a function by using its name, you are accessing its definition in a variable of that name. The scope of the function name variable is the current MAXScript scope.

The parameters for a function are either positional or keyword. Positional parameters are defined with a simple <name> and must be placed before any keyword parameters. Keyword parameters have a ':' (colon) after the name and an optional default value. The caller of the function can optionally supply keyword arguments in any order. Those not supplied will be set to the default value given, or the special value unsupplied if a default value is not given.

Using the mapped prefix on a function definition marks this function to be automatically mapped over collections. This means the function will be automatically called repeatedly on the elements of a collection if the collection is given as the first argument to the function. This allows you to define scripted functions that behave in a similar manner to the mapped built-in functions, such as copy, delete, move, and so on, which can be applied to an object set, path name pattern, or array. See Collections for more information.

Examples

function add a b = a + b

fn factorial n = if n <= 0 then 1 else n * factorial(n - 1)

mapped function rand_color x =

x.wireColor = random (color 0 0 0) (color 255 255 255)

fn starfield count extent:[200,200,200] pos:[0,0,0] =

(

local f = pos - extent / 2,

t = pos + extent / 2

for i = 1 to count do

sphere name:"star" \

radius:(random 0.1 2.0) \

position:(random f t) \

segs:4 smooth:false

)

A scripted function returns as its value the value of the body <expr>. If the body is a block-expression, the function evaluates to the value of the last expression in the block.

A function can be called recursively (that is, the function can call itself), as is the factorial function in the previous examples.

If you need to locate the source of a scripted function, you can use the showSource() function. It displays a script Editor containing the source file in which the function was defined and positioned at the function's definition. The form is:

showSource <fn>

This is useful for browsing definitions if you are working on many scripted functions, that were perhaps defined in several script files loaded with fileIn() or Run Script in the MAXScript utility.

See also

Function Variables

Function Parameters

The Return Expression

Special Notes about Function Calls


Function Variables

When you define a function, the following events occur:

  • The function definition is evaluated, creating a function value.

  • The function <name> is used to declare a new variable with that name.

  • The function value is placed into that variable.

  • The function value is returned as the result of the function definition expression.

Because the function itself is a value stored in a variable, you not only can call the function through the function name variable. By simply referring the function's variable you can also assign the function value to another variable, store it in an array, or pass it as an argument to another function.

Example

-- some 3D surface functions

fn saddle x y = sin x * sin y

fn sombrero x y = cos (x^2 + y^2) / (1 + (x^2 + y^2))

print (saddle 1 1) -- try one out

surface_functions[1] = saddle -- store the functions in an array

surface_functions[2] = sombrero

z = (surface_functions[i]) 10 10 -- call one of them from within

-- the array

build_math_mesh sombrero -- pass one in to a higher-order

-- function

The scope of a function variable is the current MAXScript scope context. The variables used inside a function have a local scope, unless the variable was already defined at a higher scope or is declared as global in the function. An exception to this is the function parameter variables, which always have a local scope.

When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. The reasons for this are described in Scope of Variables.

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.

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

Function Calls


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 Reference Assignment, 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 variable's reference does not change, and the changed compound value will still be referenced by the variable in the caller.

While in some cases you may want a function to return multiple values, it typically is not a good practice to do this by assigning to the components of a parameter variable compound value. To manipulate a compound value passed as a parameter, a compound value needs to be created in the caller and passed to the function, which can give results as shown in this example:

Script:

fn getXYZset val =

(

val.x=random -100 100

val.y=random 100 100

val.z=random val.x val.y

)

(

v1=[0,0,0]

v4=v1

getXYZSet v1

format "v1= %; v4= %\n" v1 v4

getXYZSet v4

format "v1= %; v4= %\n" v1 v4

)

Output:

getXYZset() -- result lines 1 to 5

v1= [-84,100,78.1224]; v4= [-84,100,78.1224] -- output line 10

v1= [10,100,18.6575]; v4= [10,100,18.6575] -- output line 12

OK -- result lines 6 to 12

Note that it appears the value for both variables v1 and v4 are set in the calls to getXYZset, even though only one variable is being passed. The reason for this is in line 8 variable v4 is initialized to the value of v1. What actually occurs is that in line 7 a reference to a Point3 value of [0,0,0] is created, and this reference is stored in v1. In line 8, that same reference is retrieved from v1 and assigned to v4. Rather than storing two different values, both v1 and v4 reference the same value. When you set the components of the compound value in getXYZset, the reference to the Point3 value is not being changed, and both variables still reference that value.

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

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

...

)

)


Structure Definition

You can create your own compound values in MAXScript using Structure definitions. Structure definitions let you define the layout of new 'classes' of values that you can then create and work with in your code. The syntax for a structure definition is:

struct <struct_name> ( <member> { , <member> } )

where each <member> can be one of:

<name> [ = <expr> ] -- name and optional initial value

<function_def>

Example:

struct person (name, height, age, sex)

The above example 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.

As with function definitions, a structure definition actually creates a value to represent the definition and stores it in a variable of the same name as the structure. You can therefore store the structure definitions in other compound objects or pass them as function arguments The classOf() function returns this structure definition value when applied to these values, so you can use it to test the definition of structure instances at runtime. For example:

classOf bill -> person

The struct value constructors are just like function calls and take positional argument initializers as well as keyword initializers. The elements of the new struct are filled-in in order from any positional arguments and then by name from any keyword arguments.

For example, given the following struct definition,

struct foo (name, age, height, hair="brown")

you can create instances, in several ways:

f1 = foo "bill" 23 72 -- fills in name, age, height in order

f2 = foo age:45 name:"sam" -- random named initializers

f3 = foo "mary" hair:"red" -- first name, then keywords

There are several methods associated with struct values:

getProperty <struct>

Allows you to access properties of the structure.

getPropNames

Returns the properties of the structure as an array.

copy <struct>

Creates a copy of the structure. The copy made is what is called a shallow copy - only a copy of the upper-level value itself (that is, the struct value) is created. Copies aren't made of compound values stored in the structure, rather the same compound value is stored in both struct values. This can be seen in the following example, where changing a component value of a compound value in a copy of a struct value also changes value in the original struct value:

Script:

Struct test (pos1, pos2) -- define a structure

testval = test [1,2,3] [4,5,6] -- create struct value

testval_copy=copy testval -- copy the struct value

testval_copy.pos1.x=10 -- change component value of a compound

-- value in the copy

testval -- look at original struct value

Output:

#Struct:test( -- result line 1

pos1:<data>,

pos2:<data>)

#test(pos1:[1,2,3], pos2:[4,5,6]) -- result line 2

#test(pos1:[1,2,3], pos2:[4,5,6]) -- result line 3

10 -- result line 4

#test(pos1:[10,2,3], pos2:[4,5,6]) -- result line 6

Methods


Defining Local Functions in Structures

You can define local functions in structures, providing a convenient mechanism for packaging a set of related functions and avoiding possible name conflicts when many global functions are defined, possibly by several separate scripts. For example:

struct foo

(

a, b, c,

fn baz n = sqrt (n + 1),

fn bar x y = print (x ^ 2 + y ^ 2)

)

This defines a structure definition foo with 3 elements named a, b, and c, and two local functions, bar and baz. You can access these functions as properties of either the structure definition value itself or an instance of the foo structure:

p = foo.baz q -- access as property of the structure definition value

foo.bar x y

f = foo 2 3 4

f.bar x y -- access as property of the structure instance

Local functions declared in a structure definition can make references to the member data variables defined in the structure, such that when that member function in some instance of the structure is called, the references access the members of that instance. This allows you to initialize and maintain data structures for the structure functions within the structure itself. An example of including functions that use members of the structure is shown in the following script.

Script:

struct RandVals

(

RndVals=#(), ptr, seedVal,

fn generateRV num fromVal toVal =

(

if seedVal != undefined do seed seedVal

RndVals=for i=1 to num collect random fromVal toVal

ptr=1

RndVals

),

fn deleteRv =

(

RndVals=#()

ptr=undefined

undefined

),

fn getNextRV =

(

if Nvals == 0 do return undefined

val=RndVals[ptr]

ptr += 1

if ptr > RndVals.count do ptr=1

val

),

fn sortRV = (sort RndVals),

fn setSeed val = (SeedVal = val),

fn setPointer val =

(

if val > 0 and val <= RndVals.count then

(ptr=val;true)

else

false

)

)

MyRandomVals= RandVals()

MyRandomVals.setSeed 12345

MyRandomVals.generateRV 10 0 100

MyRandomVals.getNextRV()

MyRandomVals.sortRV()

MyRandomVals.setPointer 1

MyRandomVals.getNextRV()

MyRandomVals.deleteRv()

Output:

#Struct:RandVals( -- result of struct def lines 1 to 29

generateRV:<fn>,

sortRV:<fn>,

RndVals:<data>,

deleteRv:<fn>,

getNextRV:<fn>,

seedVal:<data>,

setSeed:<fn>,

setPointer:<fn>,

ptr:<data>)

#RandVals(RndVals:#(), ptr:undefined, seedVal:undefined) -- result line 30

12345 -- result line 31

#(23, 59, 79, 68, 17, 72, 84, 16, 89, 72) -- result line 32

23 -- result line 33

#(16, 17, 23, 59, 68, 72, 72, 79, 84, 89) -- result line 34

true -- result line 35

16 -- result line 36

undefined -- result line 37

In this script, the structure has 3 data members and 6 function members. Note the references to the structure data members in the generateRV() function. In line 30, an instance of the RndVals structure is created and stored in variable MyRandomVals. In line 31, the setSeed() function in the structure instance is called, which initializes the random seed variable by storing the specified value in data member seedVal in the structure instance. In line 32, the generateRV() function in the structure instance is called, which initializes the random number using the seed value specified by setSeed(), sets up and stores an array of random numbers in data member RndVals, updates data member ptr, and then returns the random number array.

Local functions defined in structures are not stored in every instance of the structure. The local function is stored once in the structure definition and references to them in the instances refer to their definitions in the structure definition.


Structure Inherited Methods

All structures inherit from the Value class and so structure instances implement the Value methods print(), format(), classOf(), superClassOf(), isKindOf(), ==, and !=. The copy() method is the only method not inherited from Value that structures implement. It yields a top-level copy of the structure you call it on, meaning that you get a new, separate structure instance containing the same element values as the original and then you can modify that copy independently. The element values are not themselves copies, so for example, if one of the elements was an array, the copy would reference that same array, not a copy of that array.


Values

The Value class is the root class for all MAXScript classes. It supplies methods and operators that any class can use.

As described in Properties, Methods, Operators, and Literals, each class can specify external interfaces for the class. These external interfaces are broken up into the following categories:

  • Literals: Any literal form for objects of the class.

  • Constructors: The various ways you can create objects of the class.

  • Properties: Accessible parameters for objects of the class.

  • Operators: Defines the math and other symbolic operators that are defined on values in the class.

  • Methods: Defines all the functions you can call for objects of the class.

In the description of each class in MAXScript, each of these external interfaces are documented.

In the syntax forms given for methods, operators, and properties, the types of argument or property values are specified using the <type_name> convention, in which type_name describes the type of value that is allowable for that argument or property. You can, of course, use an arbitrary expression for these values, as long as it evaluates to a value of the right type. For example, <boolean> means either the true or false Boolean values.

Also indicated for function calls are those that are automatically mapped over collections. This means that the function will be automatically called repeatedly on the elements of a collection if the collection is given as the first argument to the function. See Collections for more information.


Value Common Properties, Operators, and Methods

Operators

<value> == <value>

compare if equal

<value> != <value>

compare if not equal

<value> as <class>

Converts the value to an instance of given class. See the description for each class for valid conversions. All values can be converted to class String, which yields a string with the printed representation of the value.

Methods

print <value> [ to:<stream> ] [#noMap] -- mappable

where <stream> is

( <filestream> | <stringstream> | <windowstream> )

Prints single value to Listener or optional filestream, stringstream, or windowstream, followed by a line break. If the argument value is a Collection, and #noMap is not specified, each value in the collection is printed out on a separate line. If #noMap is specified, the collection value is printed out on a single line. The printed form of all basic data value types, except for BigArray, are directly readable by the readValue() and readExpr() functions, making it simpler to read back in values printed to a file by MAXScript. If the pre-3ds max R3 print forms are required for compatibility with existing scripts, you can set the system global variable options.oldPrintStyles to true.

format <format_string> { <value> } [ to:<stream> ]

Prints one or more values to Listener or optional filestream, stringstream, or windowstream, using the format string as a template. The format string is a string that can contain plain text to print interspersed with the '%' (percent) metacharacter. Each occurrence of a '%' is replaced by the printed representation of the successive argument values following the format string. For example:

format "name:%, pos:%\n" obj.name obj.pos

generates something like:

name: box01, pos: [0, 150.0, 0.5]

format does not automatically append a line break to the output stream, so you can build up a line from several format calls and generally control layout better. An explicit '\n' newline escape character sequence is needed to place a line break in the output stream. Other escape character sequences are documented in String Literals.

classOf <value>

Returns the value's class. Each type of value has its own class. If the value is a Node value, classOf() returns the class of the world state object (the state of the node at the top of its stack). See Node : MAXWrapper for more information.

Note:

To avoid a conflict between a user class value in global variable named 'rollout' and MAXScript reserved word 'rollout' which always introduces a rollout definition the class variable name for a rollout is RolloutClass.

So, for a rollout foo you'd now say "if classOf foo == RolloutClass".

superClassOf <value>

Returns the value's superclass. A value's superclass is the class from which the value's class was derived.

isKindOf <value> <class>

Returns true if value has given class or inherits from class.

isStructDef <value>

Returns true if the value is a structure definition

isStruct <value>

Returns true if the value is a structure instance

isController <value>

Returns true if the value is a controller

getHashValue <value> <Integer oldHaskValue>

If the value is one of the supported value types, returns an integer hash value that is a factor of the value and oldHaskValue. If the value type is not supported, returns a value of undefined. The supported value types are:

Float

Integer

String

BitArray

Point3

Ray

Quat

AngAxis

EulerAngles

Matrix3

Point2

Color

Arrays containing any of the above value types


Working with Values

Print and Format

The print() and format() functions are straightforward. The format function is used when any formatting of the output is desired, or if you want to print multiple values on a line. When printing a value using either of these functions, a string representation of the value is printed. This is not the object name for those objects with names (for example a 3ds max object or material). In the following example, variable b contains a reference to a 3ds max Box object that has a material applied:

Script:

print b

print b.name

print b.material

print b.material.name

Output:

$Box:Box01 @ [-74.353745,0.000001,-19.931978]

"Box01"

Material #1:Standard

"Material #1"

The printed results above also reflect the result of a <value> as string operation, that is the result is a string representation of the object rather than the object name.

classOf, superClassOf, and isKindOf

The following table shows the hierarchy of classes and superclasses for a variable that contains a reference to a 3ds max Box object (i.e., b=box()).
 | ClassOf | SuperClassOf
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)

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 Pickbutton.


Basic Data Values

Number Values

String Values

Name Values

BooleanClass Values

Color Values

Point3 Values

Point2 Values

Ray Values

Quat Values

AngleAxis Values

EulerAngles Values

Matrix3 Values

BigMatrix Values

Box2 Values

BitArray Values

ArrayParameter Values


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 Number Literals.

Literals

[-]{<digit>}[.{<digit>}[(e | E)[+ | -]{<digit>}+] -- decimal number

0x{<hex_digit>}+ -- hexadecimal number

Examples:

123

123.45

-0.00345

1.0e-6

0x0E

0xFFE0

.1

Operators

<number> + <number>

<number> - <number>

<number> * <number>

<number> / <number>

Standard arithmetic operations. If both numbers are integers, the result is a non-rounded integer. If one or both numbers are floats, both arguments are widened to floats and the result is a float.

<number> ^ <number>

Raise the first number to the power given by the second number. If the first number is an integer, the result is a rounded integer.

- <number>

unary minus

<number> == <number>

<number> != <number>

<number> > <number>

<number> < <number>

<number> >= <number>

<number> <= <number>

Standard number comparison operations.

<number> as <class>

Converts the number to an instance of the given class. Allowed classes are:

Float

Integer

String

Time (number taken as frames)

Methods

copy <number>

Creates a new copy of the number value. This method exists primarily to support copying arrays.

abs <number>

Returns the absolute value of the number. The result is the same type as the argument.

mod <number1> <number2>

Modulo arithmetic, the remainder when number1 is divided by number2. The result is always a float.

ceil <number>

Returns the nearest whole number greater than or equal to number. The result is always a float.

floor <number>

Returns the nearest whole number less than or equal to number. The result is always a float.

acos <number>

asin <number>

atan <number>

atan2 <number> <number>

cos <number>

cosh <number>

sin <number>

sinh <number>

tan <number>

tanh <number>

Standard trigonometric functions. Angles are represented in degrees. The result is always a float.

exp <number>

log <number>

log10 <number>

pow <number> <number>

sqrt <number>

Standard transcendental functions. The result is always a float.

random <number> <number>

Returns a pseudo random number inclusively between the two arguments. Return value type is the type of the first argument.

seed <number>

Reseeds the random number generator using the specified value.

degToRad <number>

Returns the conversion of the number from degrees to radians. The result is always a float.

radToDeg <number>

Returns the conversion of the number from radians to degrees. The result is always a float.

bit.and <integer1> <integer2>

Returns the <integer> result of AND-ing the bits in integer1 and integer2

bit.or <integer1> <integer2>

Returns the <integer> result of OR-ing the bits in integer1 and integer2

bit.xor <integer1> <integer2>

Returns the <integer> result of XOR-ing the bits in integer1 and integer2

bit.not <integer1>

Returns the <integer> result of flipping the bits in integer1

bit.shift <integer1> <integer2>

Returns the <integer> result of shifting the bits in integer1 by integer2 places. If integer2 is positive, the bits are shifted to the left, if negative, to the right. The highest order bit is not carried when shifting to the left (unsigned shift operation).

bit.set <integer1> <integer2> <boolean>

Returns an <integer> result where bit integer2 of integer1 is set to the specified boolean value. Bit 1 is the lowest order (least significant) bit.

bit.flip <integer1> <integer2>

Returns an <integer> result where bit integer2 of integer1 is flipped. Bit 1 is the lowest order (least significant) bit.

bit.get <integer1> <integer2>

Returns the <boolean> state of the integer2 bit of integer1. Bit 1 is the lowest order (least significant) bit.

bit.intAsChar <integer>

Returns a <string> result of length 1 containing the character corresponding to the integer value. Only the lowest order 8-bits (16-bits for localized versions of 3ds max) of the integer are used.

bit.charAsInt <string>

Returns the <integer> value corresponding to the first character of the string.

bit.intAsHex <integer>

Returns a <string> value containing the hex representation of the integer.

Notes

The range of valid Integers in MAXScript is -2,147,483,648 to 2,147,483,647. If you perform calculations that result in integers outside of this range, you will get integer overflow errors that are not detected by MAXScript. You must take care in designing your code to prevent or detect this overflow yourself. The result of an overflow is typically a large number of the wrong sign. Dividing an integer by 0 will result in a MAXScript system exception.

A Float in MAXScript has an absolute value range of is 1.18E-38 to 3.40E38, with a precision of one part in 1.0E7. If you perform calculations that result in floats with an absolute value less than this range, the result will be stored as 0.0. If you perform calculations that result in floats with an absolute value larger than this range, the result will be stored as a special value that represents infinity, 1.#INF. Adding, subtracting, or multiplying a number by 1.#INF results in a value of 1.#INF. Dividing a number by 1.#INF results in a value of 0.0. Dividing 0.0 by 0.0 or 1.#INF by 1.#INF, multiplying 1.#INF by 0, or 1.#INF from 1.#INF results in a special value that represents an indeterminate number, -1.#IND. Adding, subtracting, multiplying, or dividing a number by -1.#IND results in a value of -1.#IND.

When you display or print a Float, MAXScript prints the value to the 6th significant digit. The following table shows examples of values stored to a MAXScript variable, the value as stored, and the value as displayed.
Input Value | Stored Value | Displayed Value
1.23456789 | 1.23456788 | 1.23457
1.1 | 1.10000002 | 1.1
1.01 | 1.00999999 | 1.01
1.001 | 1.00100004 | 1.001
1.0001 | 1.00010001 | 1.0001
1.00001 | 1.00001001 | 1.00001
1.000001 | 1.00000095 | 1.0
1.0000001 | 1.00000011 | 1.0
1.00000001 | 1.00000000 | 1.0
100017.911 | 100017.914 | 100018.0

Examples

The following script shows the use of various literals, constructors, properties, operators, and methods of the Number class.

Script:

-- numbers test bed

i=10 -- assign integers to variables

j=20

i/j -- integer divide, result is integer

i=i as float -- convert i to a float

i/j -- float divide, result is float

i += 1 -- increment i by 1

if i < j do i=2.^3 -- if i is less than j, set i to 2 to the 3rd power

mod j i -- return remainder of j divided by i

cos 30.0 -- return cosine of 30 degrees

sqrt j -- return square root of j

seed 12345 -- seed the random number generator

for k=1 to 5 do print (random i j) -- print out 3 random numbers

Output:

10 -- result of line 2

20 -- result of line 3

0 -- result of line 4 (10/20)

10.0 -- result of line 5

0.5 -- result of line 6 (10./20)

11.0 -- result of line 7

8.0 -- result of line 8 (2.^3)

4.0 -- result of line 9

0.866025 -- result of line 10

4.47214 -- result of line 11 (sqrt 20)

OK -- result of line 12

10.7775 -- output from line 13 (random 8. 20)

15.0183

17.4467

16.1027

10.1344

OK -- result of line 13


String Values

The String class defines the characteristics of character strings. The character strings can be of any length.

Literal

"<characters>"

See String Literals for a description of String literals.

Constructors

<value> as string

Converts any value into its string representation.

Properties

<string>.count : Integer, read-only

The number of characters in the string.

Operators

<string> + <string>

Returns a new string that is the concatenation of the two strings.

<string> == <string>

<string> != <string>

<string> > <string>

<string> < <string>

<string> >= <string>

<string> <= <string>

Standard lexical string comparisons (case sensitive). To perform a case insensitive comparison, first convert the strings to Name values.

<string>[<index_number>]

Returns indexed character as a single-character string, index starts at 1.

<string>[<index_number>] = <single_character_string>

Sets indexed character to character given.

<string> as <class>

Converts the string to an instance of the given class. You can convert a string into a Name value using the as operator, for example:

"Foo" as name -- returns #foo

You can also convert strings to numbers using the as operator. For example:

"123.4" as float -- returns 123.4

You can use any of the Number classes as a target class - Number, Float, or Integer. If you use Number, the appropriate class will be used depending on the syntax of the number in the string.

You can convert a string to a StringStream value using the as operator. For example:

"$box01" as stringstream -- returns the string as a stringstream

Converting a string to a StringStream value allows you to read through a string using the MAXScript's text file I/O operations. See StringStream Values 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.

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 Scope of Variables and Accessing Locals and Other Items in a Rollout from External Code.

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

filterString <string> <token_string>

Parses string based on token_string and returns an array of strings. filterString splits the input string into substrings based on the characters given in token_string, and returns each substring as a member of the array. The token_string is simply a list of 'splitter characters' - when the string is scanned, any occurrence of any of the tokens is regarded as the start of a substring. This function is useful for file import/export scripts, or for any type of manual parsing. For example:

filterString "MAX Script, is-dead-funky" ", -"

would return

#("MAX","Script","is","dead","funky")

replace <string> <from_integer> <length_integer> <new_string>

Returns a new string where the substring in string starting at index from_integer, and of length length_integer, is replaced with the new_string. new_string can be any length. The sum of from_integer and length_integer must be less than the length of string. An example usage is:

s="1234567890"

s1=replace s 5 3 "inserted string" -- returns "1234inserted string890"

substring <string> <from_integer> <length_integer>

Returns a new string consisting of the substring in string starting at index from_integer, and of length length_integer. If the sum of from_integer and length_integer is greater than the length of string, a shorter string is returned containing as many characters as are available in the source. If a negative value is specified for length_integer, the remainder of the string starting from from_integer is returned. For example:

s = "Balerofon"

ss = substring s 5 3 -- returns "rof"

ss = substring s 5 -1 -- returns "rofon"

ss = substring s 5 100 -- returns "rofon"

matchPattern <string> pattern:<pattern_string> \

[ ignoreCase:<boolean> ]

Returns true if string is matched by the wild card pattern_string, false otherwise. The comparison is case-insensitive unless ignoreCase:false is specified. For example:

s="text1"

matchPattern s pattern:"text?" -- returns true

matchPattern s pattern:"T*" -- returns true

matchPattern s pattern:"T*" ignoreCase:false -- returns false

matchPattern s pattern:"s*" -- returns false

Examples

The following script shows the use of various literals, constructors, properties, operators, and methods of the String class.

Script:

-- strings test bed

fn uppercase instring = -- beginning of function definition

( local upper, lower, outstring -- declare variables as local

upper="ABCDEFGHIJKLMNOPQRSTUVWXYZ" -- set variables to literals

lower="abcdefghijklmnopqrstuvwxyz"

--

-- create an unique copy of the string referenced by instring, and store

-- reference to unique copy in outstring

outstring=copy instring

--

-- increment from 1 to number of character in string

for i=1 to outstring.count do

--

-- see if the single character at index i in outstring is present in string lower

-- If so, j equals position in string lower. If not, j equals undefined

( j=findString lower outstring[i]

--

-- if character was found in lower, replace with corresponding character in upper

if (j != undefined) do outstring[i]=upper[j]

)

outstring -- value of outstring will be returned as function result

)-- end of fn uppercase

--

s1="AbCdEfGh" -- set variable to literal

s2=uppercase s1 -- call function uppercase, passing s1 as parameter

if s1 == s2 do print "strings s2 and s3 are the same" -- compare strings

if s1 != s2 do print "strings s1 and s2 are different"

--

theObject="sphere" -- set variable to literal

theRadius= (random 10. 100.) as string -- convert number to string

-- concatenate strings and execute string

myObject=execute (theObject + " radius:" + theRadius)

Output:

uppercase() -- result to function definition

"AbCdEfGh" -- result of line 24

"ABCDEFGH" -- result of line 25

undefined -- result of line 26 - strings not equal,

-- and no else expression in if expression

"strings s1 and s2 are different" -- output from line 27

"strings s1 and s2 are different" -- result of line 27

"sphere" -- result of line 29

"75.4091" -- result of line 30

$Sphere:Sphere01 @ [0.0,0.0,0.0] -- result of line 32. Execute function

-- created a sphere object


Name Values

The Name class defines the characteristics of names. Names are primarily used as parameters in function calls to signify one of a set of options.

Literal

#<var_name>

See Names for a description of Name literals.

Constructors

<string> as name

Converts a String value into a name

Operators

<name> == <name>

<name> != <name>

<name> < <name>

<name> > <name>

<name> <= <name>

<name> >= <name>

Comparison of names is caseless alphabetic. Among other things, this allows arrays of names to be sorted using the array sort function.

Examples

The following script shows the use of various literals, constructors, and operators of the Name class.

Script:

-- name test bed

name1=#Hello -- set variable to name literal

name2="HELLO" as name -- convert string to name

if name1 == name2 do print "names are equal" -- compare the names

box_props=getpropnames box -- get the properties of box class

sort box_props -- sort the property names

Output:

#Hello -- result of line 2

#Hello -- result of line 3

"names are equal" -- output from line 4

"names are equal" -- result of line 4

-- following are the results of lines 5 and 6

#(#height, #length, #lengthsegs, #width, #widthsegs, #mapCoords, #heightsegs)

#(#height, #heightsegs, #length, #lengthsegs, #mapCoords, #width, #widthsegs)


BooleanClass Values

The BooleanClass class defines the characteristics of values that can only have one of two states.

Literals

true

false

on -- equivalent to true

off -- equivalent to false

Operators

not <boolean>

true if boolean=false, false if boolean=true

<boolean> and <boolean>

true if both boolean values are true

<boolean> or <boolean>

true if either boolean value is true

Notes

The boolean and and or evaluations are non-strict. This means that only the first boolean may be evaluated to determine the overall result:

  • If the first operand is false in an and expression, the result must be false, therefore, the second operand is not evaluated.

  • If the first operand is true in an or expression, the result must be true, therefore, the second operand is not evaluated.

This saves execution time and enables useful shorthand notation. For example, if you want to calculate 'sin a' if the value of variable 'a' isn't undefined, you could use the example below:

if a != undefined and sin a > 0 then ..

Examples

The following script shows the use of various literals and operators of the BooleanClass class.

Script:

-- boolean test bed

bool1=true -- set variables to boolean literals

bool2=on

if bool1 and bool2 do print "booleans are equal" -- compare the booleans

-- define an "exclusive or" function - returns true if only one of the

-- inputs is true

fn xor b1 b2 = (not (b1 and b2)) and (b1 or b2)

xor false false -- evaluate 4 combinations of inputs to xor

xor false true

xor true false

xor true true

Output:

true -- result of line 2

true -- result of line 3

"booleans are equal" -- output from line 4

"booleans are equal" -- result of line 4

xor() -- function definition

false -- result of line 8

true -- result of line 9

true -- result of line 10

false -- result of line 11


Color Values

All the places that colors turn up in MAXScript (such as wireColor, light color, etc.) are represented by instances of the Color class. You can also use Point3 values as color specifiers.

Literals

red

green

blue

white

black

orange

yellow

brown

gray

predefined MAXScript globals

Constructors

color <r> <g> <b> [ <a> ]

r,g,b and optional alpha are float values in the range 0 to 255

<point3> as color

interprets x as r, y as g, z as b

Properties

<color>.red or .r : Float

<color>.green or .g : Float

<color>.blue or .b : Float

<color>.alpha or .a : Float

color component properties

<color>.hue or .h : Float

<color>.saturation or .s : Float

<color>.value or .v : Float

derived properties

Operators

<color> == <color>

<color> != <color>

<color> + <color_or_number>

<color> - <color_or_number>

<color> * <color_or_number>

<color> / <color_or_number>

Channel-by-channel math operations. Numbers operate on r,g,b,a channels equally.

- <color>

unary minus

Methods

copy <color>

Creates a new copy of the color value. For example:

newClr = copy oldClr

The new value contains a copy of the input color value, and is independent of the input color value.

random <from_color> <to_color>

Returns a random color between the given colors. The alpha component of the result will always be 255.

composite <color1> <color2>

Composites color1 over color2 through color1's alpha. This function is equivalent to:

color1 + color2*((255. - color1.alpha)/255.)

-- 3D Noise Functions

noise3 <color>

noise4 <color> <phase_float>

turbulence <color> <frequency_float>

fractalNoise <color> <H_float> <lacunarity_float> <octaves_float>

See Point3 Values 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.

Script:

-- color test bed

magenta=color 255 255 0 255 -- create colors using constructors

aqua = [0, 255, 255] as color

aqua.v /= 2. -- reduce "strength" of aqua color

aqua

aqua.alpha=128 -- set aqua to 50% opacity

aqua

lightGray=white/4 -- create light gray color by dividing

-- each component of white by 4

composite aqua lightGray -- composite light gray over aqua

random black white -- generate a random color

Output:

(color 255 255 0) -- result of line 2. Note that if

-- alpha=255 it is not displayed

(color 0 255 255) -- result of line 3

127.5 -- result of line 4 - value property of aqua

(color 0 127.5 127.5) -- result of line 5 - color of aqua

128 -- result of line 6 - alpha property of aqua

(color 0 127.5 127.5,128) -- result of line 7 - color of aqua

(color 63.75 63.75 63.75) -- result of line 8 - each component divided by 4

(color 31.75 159.25 159.25 159.75) -- result of line 10

(color 170.944 109.543 74.1957) -- result of line 11


Point3 Values

The Point3 class defines the characteristics of points in 3D space. These values are also known as 3D vectors, and contain 3 component floating point numbers. All the coordinates passed to and from 3ds max are in these values. See also 2D and 3D Point Literals.

Literals

[ <expr>, <expr>, <expr> ]

Examples:

[x, y, z]

[10, 10, 10]

[sin x, cos y, tan z]

x_axis -- equivalent to [1,0,0]

y_axis -- equivalent to [0,1,0]

z_axis -- equivalent to [0,0,1]

Constructors

point3 <x> <y> <z>

<color> as point3

Properties

<point3>.x : Float -- the x coordinate

<point3>.y : Float -- the y coordinate

<point3>.z : Float -- the z coordinate

Operators

<point3> == <point3>

<point3> != <point3>

<point3> + <point3_or_number>

<point3> - <point3_or_number>

<point3> * <point3_or_number>

<point3> / <point3_or_number>

Standard vector arithmetic. If the second operand is a number, the operation is performed on each component of the value.

<point3> * <matrix3>

Transforms point3 into the coordinate system specified by matrix3.

<point3> * <quat>

rotates point3

- <point3>

unary minus

Methods

copy <point3>

Creates a new copy of the point3 value. For example:

newPos = copy oldPos

The new value contains a copy of the input point3 value, and is independent of the input point3 value.

length <point3>

Returns the length of the vector.

dot <point3> <point3>

Returns the vector dot product.

cross <point3> <point3>

Returns the vector cross product.

normalize <point3>

Returns the point3 value normalized such that the vector length equals 1.

distance <point3> <point3>

Returns the distance between the points - length of (point 2 – point 1).

random <point3> <point3>

Generates a pseudo-random point between the given points.

arbAxis <point3>

Returns a Matrix3 value representing an arbitrary axis system using point3 as the "up" direction.

matrixFromNormal <point3>

Returns a Matrix3 value with the normal specified by the given point as the Z axis. The translation portion of the Matrix3 value will be [0,0,0]. The components of the scale portion are the inverse of the values required to normalize the point3 value. For example,

MatrixFromNormal [0,0,1]

MatrixFromNormal [0,1,1]

will return

(matrix3 [1,0,0], [0,1,0], [0,0,1], [0,0,0])

(matrix3 [0,-0.707107,0.707107] [1.41421,0,0] [0,1,1] [0,0,0])

-- 3D Noise Functions

noise3 <point3>

A floating point noise function over 3D space, implemented by a pseudo-random tricubic spline. The return value is in the range -1.0 to +1.0. Given the same point3 value, the noise3() function always returns the same value.

noise4 <point3> <phase_float>

The same function as noise3 in which the phase can be varied using the second parameter. The return value is in the range -1.0 to +1.0.

turbulence <point3> <frequency_float>

This is a simple fractal-loop turbulence built on top of the noise3 function. The second parameter controls the frequency of the turbulence. The return value is in the range 0.0 to +1.0.

fractalNoise <point3> <H_float> <lacunarity_float> <octaves_float>

This is a fractal function of 3D space implemented using fractional Brownian motion. The function is homogeneous and isotropic. It returns a float.

The parameters are as follows:

point3 - The point in space at which the noise is computed.

H_float - The fractal increment parameter in the range [0,1]. When H_float is 1 the function is relatively smooth; as H_float goes to 0, the function approaches white noise.

lacunarity_float - The gap between successive frequencies, best set at 2.0.

octaves_float - The number of frequencies in the function.

All the noise functions are based on code and algorithms in the book "Texturing and Modeling: A Procedural Approach", Musgrave, Peachey, Perlin and Worley. Academic Press, ISBN: 0-12-228760-6.

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

Output

The following figures show the bitmap generated by the above script for each noise function type.

noise3

noise4

turbulence

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.

Literals

[ <expr>, <expr> ]

Examples:

[x, y]

[10, 20]

[sin x, cos x]

Constructors

point2 <x> <y> -- x and y are numbers

<point3> as point2 -- created from the x and y components of the point3

Properties

<point2>.x : Float

<point2>.y : Float

Operators

<point2> == <point2>

<point2> != <point2>

<point2> + <point2_or_number>

<point2> - <point2_or_number>

<point2> * <point2_or_number>

<point2> / <point2_or_number>

Standard vector arithmetic. If the second operand is a number it does scalar arithmetic on vector.

- <point2>

unary minus

Methods

copy <point2>

Creates a new copy of the point2 value. For example:

newPoint = copy oldPoint

The new value contains a copy of the input point2 value, and is independent of the input point2 value.

random <point2> <point2>

Generates a pseudo-random point between the given points.

length <point2>

Returns the length of the vector.

distance <point2> <point2>

Returns the distance between the points - length of (point 2 – point 1).

normalize <point2>

Returns the point2 value normalized such that the vector length equals 1.


Ray Values

The Ray class defines the characteristics of a ray in 3D space. A ray has two Point3 components, one defining a start position and the other a direction vector for the ray.

Constructors

ray <pos_point3> <dir_point3>

Returns a new ray with given position and direction vector.

<node> as ray

Takes a scene object that has a target, such as a tape measure or a target camera and returns a ray from the object to the target. Returns undefined if the object has no target.

Properties

<ray>.pos : Float

<ray>.position : Float -- pos and position are synonyms

<ray>.dir : Point3 -- unit normalized direction vector

Methods

copy <ray>

Creates a new copy of the ray value. For example:

newRay = copy oldRay

The new value contains a copy of the input ray value, and is independent of the input ray value.


Quat Values

The Quat class provides a compact representation for orientation in three space and provides methods to perform Quaternion algebra. Quaternions are used to store object rotations in 3ds max. A quaternion is made up of four terms: a real scalar part which specifies the amount of rotation and an imaginary vector part which defines the axis of rotation. If the quaternion is normalized, the scalar term equals the cosine of half the angle of rotation, the vector term is the axis of rotation, and the magnitude of the vector term equals the sine of half the angle of rotation.

Interpolation between two key frame orientations is much easier using quaternions and produces smooth and natural motion. Unlike Euler angles, no numerical integration is necessary; quaternions provide an analytic result (no approximations).

Rotations in MAXScript follow the right-hand-rule, namely positive angles rotate counter-clockwise about positive axes, consistent with the convention in the 3ds max UI.

Constructors

quat <x_float> <y_float> <z_float> <w_float>

The x, y, z values make up the vector portion. w is the angle of rotation about the vector.

quat <degrees_float> <axis_point3>

<angleaxis> as quat

<eulerangle> as quat

<matrix3> as quat -- extracts the rotation component as a quat

Properties

<quat>.w : Float

<quat>.x : Float

<quat>.y : Float

<quat>.z : Float

quaternion complex components as Floats

<quat>.angle : Float

<quat>.axis : Point3

derived properties - an angle in degrees and a rotation axis

Operators

<quat> + <quat>

<quat> - <quat>

<quat> * <quat_or_number>

<quat> / <number>

- <quat>

Quaternion algebra

<quat> * <matrix3>

Quaternion algebra using rotation portion of the matrix3

<quat> == <quat>

<quat> != <quat>

<quat> as <class>

quats can convert to Matrix3's, Angleaxis's, Eulerangle's

Methods

copy <quat>

Creates a new copy of the quat value. For example:

newQuat = copy oldQuat

The new value contains a copy of the input quat value, and is independent of the input quat value.

isIdentity <quat>

Returns true if the quaternion is equal to the identity quaternion (x=y=z=0.0; w=1.0).

normalize <quat>

Returns a normalized quat, dividing each term of the input quat by a scale factor such that the resulting sum of the squares of all parts equals unity.

inverse <quat>

Returns the inverse of the quaternion (1/q).

conjugate <quat>

Returns the conjugate of a quaternion.

logN <quat>

Returns the natural logarithm of UNIT quaternion.

exp <quat>

Returns the exponentiated quaternion (where q.w=0).

slerp <start_quat> <end_quat> <number>

Returns a spherical linear interpolation of UNIT quaternions. As number goes from 0 to 1, the returned value goes from start_quat to end_quat.

LnDif <p_quat> <q_quat>

Returns the "log difference" of two quaternions as:

logN ((inverse p_quat)*q_quat)

qCompA <prev_quat> <now_quat> <next_quat>

Compute a, the term used in Boehm-type interpolation:

a = now_quat * exp(-(1/4)*(logN((inverse now_quat)*next_quat)+

logN((inverse now_quat)*prev_quat)))

squad <p_quat> <a_quat> <b_quat> <q_quat> <number>

slerp (slerp p_quat q_quat number) \

(slerp a_quat b_quat number) \

(2*(1-number)*number)

qorthog <quat> <axis_point3>

Returns quat rotated by 180 degrees (quaternion space metric) about the specified axis axis_point3.

transform <quat> <matrix3>

Returns the transformation of the specified quaternion by the specified matrix.

squadrev <angle_number> <axis_point3> <start_quat> \

<start_tangent_quat> <end_tangent_quat> \

<end_quat> <number>

Returns quaternion interpolation for angles > 2PI where angle_number is angle of rotation, and axis_point3 is axis of rotation. As number goes from 0 to 1, the returned value goes from start_quat to end_quat.

random <quat> <quat>

Returns a random rotation between the two quats, using Slerp.

Related Methods

quatToEuler <quat> order:<eulertype_integer>

eulerToQuat <eulerAngle> order:<eulertype_integer>

Convert between quat and euler angle values. The optional order parameter specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:

1 - XYZ

2 - XZY

3 - YZX

4 - YXZ

5 - ZXY

6 - ZYX

7 - XYX

8 - YZY

9 - ZXZ

getEulerQuatAngleRatio <quat1> <quat2> \

<eulerAngles1> <eulerAngles2> \

[angle:<eulertype_integer>]

When converting a series of quat values to eulerAngles values, it is possible for sign flips to occur in the eulerAngles values. This is due to the fact that one single quat value can be expressed through many different eulerAngles values. This flip can be detected by based on the eulerAngles/quat ratio. The eulerAngles/quat ratio is the relation of the angle difference in eulerAngles space to the angle difference in quat space. If this ratio is bigger than PI the rotation between the two quat to eulerAngles conversions. This method returns the eulerAngles/quat angle ratio between the two quat to eulerAngles conversions as a float value. The actual detection of the flip is dependent on the amount of rotation in between conversions. The smaller the amount of rotation, the more accurate the detection is. The parameters to this method are:

quat1 and quat2 are the previous and current rotation values.

eulerAngles1 and eulerAngles2 are the previous and current converted rotation angles.

The optional eulertype_integer parameter specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:

1 - XYZ

2 - XZY

3 - YZX

4 - YXZ

5 - ZXY

6 - ZYX

7 - XYX

8 - YZY

9 – ZXZ


AngleAxis Values

The AngleAxis class provides a representation for orientation in 3D space using an angle in degrees and a rotation axis. This class is similar to a quaternion, except that a normalized quaternion only represents -PI to +PI rotation. Angles can be greater than 360 and so specify multiple revolutions, unlike quaternions. Rotations follow the right-hand-rule.

Constructors

angleaxis <degrees_float> <axis_point3>

<quat> as angleaxis

<eulerangle> as angleaxis

<matrix3> as angleaxis

extracts the rotation component as an angleaxis

Operators

<angleaxis> == <angleaxis>

<angleaxis> != <angleaxis>

<angleaxis> as <class>

AngleAxis can convert to Matrix3's, Quat's, Eulerangle's

Properties

<angleaxis>.angle : Float

<angleaxis>.axis : Point3

<angleaxis>.numrevs : Integer

Methods

copy <angleaxis>

Creates a new copy of the angleaxis value. For example:

newAngleAxis = copy oldAngleAxis

The new value contains a copy of the input angleaxis value, and is independent of the input angleaxis value.

random <angleaxis> <angleaxis>

Random rotation in degrees, but uses quat Slerp, so loses multiple revolution angles.


EulerAngles Values

The EulerAngles class provides a representation for orientation in 3D space using rotation angles in degrees about each axis. Angles can be greater than 360 and so specify multiple revolutions. Rotations follow the right-hand-rule.

Constructors

eulerAngles <x_degrees> <y_degrees> <z_degrees>

<quat> as eulerAngles

<angleAxis> as eulerAngles

<matrix3> as eulerAngles

Extracts the rotation component as an eulerAngles.

Operators

<eulerAngles> == <eulerAngles>

<eulerAngles> != <eulerAngles>

<eulerAngles> as <class>

eulerAngles can convert to Matrix3, Quat, angleAxis values

Properties

<eulerAngles>.x : Float

<eulerAngles>.y : Float

<eulerAngles>.z : Float

Rotation about each primary axis in float degrees

Methods

copy <eulerAngles>

Creates a new copy of the eulerAngles value. For example:

newEulerAngles = copy oldEulerAngles

The new value contains a copy of the input eulerAngles value, and is independent of the input eulerAngles value.

random <eulerAngles> <eulerAngles>

Random rotation between the eulerAngles, but uses quat Slerp, so loses multiple revolution angles.

quatToEuler <quat> order:<eulertype_integer>

eulerToQuat <eulerAngle> order:<eulertype_integer>

Convert between quat and euler angle values. The optional order parameter specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:

1 - XYZ

2 - XZY

3 - YZX

4 - YXZ

5 - ZXY

6 - ZYX

7 - XYX

8 - YZY

9 - ZXZ

getEulerQuatAngleRatio <quat1> <quat2> \

<eulerAngles1> <eulerAngles2> \

[angle:<eulertype_integer>]

When converting a series of quat values to eulerAngles values, it is possible for sign flips to occur in the eulerAngles values. This is due to the fact that one single quat value can be expressed through many different eulerAngles values. This flip can be detected by based on the eulerAngles/quat ratio. The eulerAngles/quat ratio is the relation of the angle difference in eulerAngles space to the angle difference in quat space. If this ratio is bigger than PI the rotation between the two quat to eulerAngles conversions. This method returns the eulerAngles/quat angle ratio between the two quat to eulerAngles conversions as a float value. The actual detection of the flip is dependent on the amount of rotation in between conversions. The smaller the amount of rotation, the more accurate the detection is. The parameters to this method are:

quat1 and quat2 are the previous and current rotation values.

eulerAngles1 and eulerAngles2 are the previous and current converted rotation angles.

The optional eulertype_integer specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:

1 - XYZ

2 - XZY

3 - YZX

4 - YXZ

5 - ZXY

6 - ZYX

7 - XYX

8 - YZY

9 - ZXZ

getEulerMatAngleRatio <matrix3_1> <matrix3_2> \

<eulerAngles1> <eulerAngles2> \

[angle:<eulertype_integer>]

This method parallels the getEulerQuatAngleRatio() method. This method is identical to getEulerQuatAngleRatio() with the exception that matrix3 values are passed rather than quat values.


Matrix3 Values

The Matrix3 class implements a 4x3 3D transformation matrix object. The transform matrix is a 3D homogeneous matrix typically used to hold object coordinate systems and transformations.

Constructors

matrix3 <row1_point3> <row2_point3> <row3_point3> <row4_point3>

matrix from row vectors

matrix3 0

zero matrix

matrix3 1

identity matrix

<quat> as matrix3

<angleaxis> as matrix3

<eulerangles> as matrix3

rotation matrices

rotateXMatrix <number> -- all angles in degrees

rotateYMatrix <number>

rotateZMatrix <number>

rotation matrices

transMatrix <point3>

translation matrix

scaleMatrix <point3>

scale matrix

rotateYPRMatrix <yaw_number> <pitch_number> <roll_number>

Returns a Matrix3 value for use as a rotation transformation by specifying yaw, pitch and roll angles. All angles are in degrees.

matrixFromNormal <point3>

Returns a Matrix3 value with the normal specified by the given point as the Z axis. The translation portion of the Matrix3 value will be [0,0,0]. The components of the scale portion are the inverse of the values required to normalize the point3 value. For example,

MatrixFromNormal [0,0,1]

MatrixFromNormal [0,1,1]

will return

(matrix3 [1,0,0], [0,1,0], [0,0,1], [0,0,0])

(matrix3 [0,-0.707107,0.707107] [1.41421,0,0] [0,1,1] [0,0,0])

Operators

<matrix3> + <matrix3>

<matrix3> - <matrix3>

<matrix3> * <matrix3>

<matrix3> as <class>

Matrix3's can convert to Quat's, AngleAxis, EulerAngles using the matrix's rotation component

Properties

<matrix3>.row1 : Point3

<matrix3>.row2 : Point3

<matrix3>.row3 : Point3

<matrix3>.row4 : Point3

<matrix3>.translation : Point3

read/write access to rows. Row4 is the translation.

<matrix3>.rotationpart : Quat, read-only

<matrix3>.translationpart : Point3, read-only

<matrix3>.scalerotationpart : Quat, read-only

<matrix3>.scalepart : Point3, read-only

access to various transforms, with the remaining transforms zero-ed out.

<matrix3>.determinantsign : Integer, read-only

returns sign of the matrix's determinant

Methods

copy <matrix3>

Creates a new copy of the matrix3 value. For example:

newMatrix3 = copy oldMatrix3

The new value contains a copy of the input matrix3 value, and is independent of the input matrix3 value.

isIdentity <matrix3>

Returns true if the matrix is equal to the identity matrix.

inverse <matrix3>

Returns the inverse of the matrix.

xformMat <transform_matrix3> <space_matrix3>

Returns the transform matrix transformed into a particular space. For example, say you have a rotation you want to apply, but you want to perform the rotation in another coordinate system. To do this, you typically transform into the space of the coordinate system, then apply the transformation, and then transform out of that coordinate system. This method transformats matrix transform_matrix3 into the space of matrix space_matrix3. The resulting matrix3 value is calculated as space_matrix3 * transform_matrix3 * inverse(space_matrix3).

identity <matrix3> -- mapped function

Sets the input matrix or matrices to the identity matrix. If the parameter is a single matrix, this function returns an identity matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 values are replaced with the identity matrix.

zero <matrix3> -- mapped function

Sets the input matrix or matrices to the zero matrix. If the parameter is a single matrix, this function returns an zero matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 values are replaced with the zero matrix.

orthogonalize <matrix3> -- mapped function

Sets the input matrix or matrices to the an "unbiased" orthogonalization of the matrix. An orthogonal matrix has an axis system where each axis is 90 degrees from the others (it's not skewed). If the parameter is a single matrix, this function returns the orthogonalized matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the orthogonalized matrix value(s).

translate <matrix3> <point3> -- mapped function

Applies an incremental translation transformation to the input matrix or matrices. This is equivalent to multiplying on the RIGHT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

rotateX <matrix3> <number> -- mapped functions -- all angles in degrees

rotateY <matrix3> <number>

rotateZ <matrix3> <number>

rotate <matrix3> <quat>

Applies an incremental rotation transformation to the input matrix or matrices. This is equivalent to multiplying on the RIGHT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

scale <matrix3> <point3> [ <boolean> ] -- mapped function

Applies an incremental scale transformation to the input matrix or matrices. This is equivalent to multiplying on the RIGHT by the transform. If <boolean> is true, the translation component is scaled. If <boolean> is false the translation component is unaffected. When 3ds max was originally written there was a bug in the code for this method where the translation portion of the matrix was not being scaled. This meant that when a matrix was scaled the bottom row was not scaled. Thus it would always scale about the local origin of the object, but it would scale the world axes. When this bug was discovered, dependencies existed in the code upon this bug. Thus it could not simply be fixed because it would break the existing code that depended upon it working the incorrect way. To correct this boolean parameter was added. If it is set to true, the translation component will be scaled correctly. If not specified, the boolean defaults to false, and the code behaves the old way. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

preTranslate <matrix3> <point3> -- mapped function

Applies an incremental translation transformation to the input matrix or matrices. This is equivalent to multiplying on the LEFT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

preRotateX <matrix3> <number> -- mapped functions -- all angles in degrees

preRotateY <matrix3> <number>

preRotateZ <matrix3> <number>

preRotate <matrix3> <quat>

Applies an incremental rotation transformation to the input matrix or matrices. This is equivalent to multiplying on the LEFT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

preScale <matrix3> <point3> [ <boolean> ] -- mapped function

Applies an incremental scale transformation to the input matrix or matrices. This is equivalent to multiplying on the LEFT by the transform. If <boolean> is true, the translation component is scaled. If <boolean> is false the translation component is unaffected. If not specified, the boolean defaults to false. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

Related Methods

getEulerMatAngleRatio <matrix3_1> <matrix3_2> \

<eulerAngles1> <eulerAngles2> \

[angle:<eulertype_integer>]

When converting a series of matrix3 values to eulerAngles values, it is possible for sign flips to occur in the eulerAngles values. This is due to the fact that one single matrix3 value can be expressed through many different eulerAngles values. This flip can be detected by based on the eulerAngles/matrix3 ratio. The eulerAngles/matrix3 ratio is the relation of the angle difference in eulerAngles space to the angle difference in matrix3 space. If this ratio is bigger than PI the rotation between the two matrix3 to eulerAngles conversions. This method returns the eulerAngles/matrix3 Angle ratio between the two matrix3 to eulerAngles conversions as a float value. The actual detection of the flip is dependent on the amount of rotation in between conversions. The smaller the amount of rotation, the more accurate the detection is. The parameters to this method are:

matrix3_1 and matrix3_2 are the previous and current transform matrix values.

eulerAngles1 and eulerAngles2 are the previous and current converted rotation angles.

The optional eulertype_integer specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:

1 - XYZ

2 - XZY

3 - YZX

4 - YXZ

5 - ZXY

6 - ZYX

7 - XYX

8 - YZY

9 - ZXZ


BigMatrix Values

BigMatrix Values, BigMatrixRowArray Values

The BigMatrix class implements an MxN matrix for situations and calculations where the usual 4x3 Matrix3 class is not adequate. The BigMatrixRowArray class implements an N element vector. Each row in a BigMatrix value is a BigMatrixRowArray value. Only Float values can be stored in the elements of a BigMatrixRowArray.

Constructors

BigMatrix <rows> <columns>

Properties

<BigMatrix>.rows : Integer, read-only

<BigMatrix>.columns : Integer, read-only

Operators

<BigMatrix> + <BigMatrix> -- both BigMatrix values must have same size

<BigMatrix>[<int_row>] -- returns BigMatrixRowArray of indexed row

<BigMatrixRowArray>[<int_column>] -- returns float value of indexed column

<BigMatrixRowArray>[<int_column>] = <float_value> -- sets value in the indexed column

Because accessors are themselves operands, these definitions are recursive, which means that you can string accessors together:

<BigMatrix>[<int_row>][<int_column>] -- returns float value of indexed row and column

<BigMatrix>[<int_row>][<int_column>] = <float_value> -- sets value in the matrix

Methods

invert <BigMatrix>

Inverts the matrix in place, i.e., the input BigMatrix itself is modified. The return value is also the inverted matrix. Note that this method only works if this matrix is "square", i.e. if m = n.

transpose <BigMatrix>

Returns the transpose of <BigMatrix>, i.e. result BigMatrix[i][j] = BigMatrix[j][i].

clear <BigMatrix>

Frees all the elements and sets the matrix size to be 0x0

setSize <BigMatrix> <rows> <columns>

Deletes the current elements and sets the size of the matrix to rows x columns.

identity <BigMatrix> -- mapped function

If the number of rows and columns are equal, this method sets the matrix to the identity (diagonal elements = 1, all other elements = 0). If the number of rows and columns are not equal, it does nothing. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input BigMatrix value(s) are set to the identity.

Notes

A BigMatrix object is a compound object, similar to an array of arrays. All of the BigMatrix methods operate directly on the components of the input BigMatrix. As described in Reference Assignment, this can cause complications to occur if a BigMatrix object referenced by more than one variable. If you assign a new value to an element of the matrix, or use any of the BigMatrix methods, the same object is still referenced by the variables. This can be seen in the following example.

Script

bm1=bigmatrix 2 2

for i=1 to 2 do for j=1 to 2 do bm1[i][j]=random 0 10

bm2=bm1

invert bm1

bm2

Output

#BigMatrix( -- result of line 1, contents of bm1

[0.00,0.00],

[0.00,0.00]

)

OK -- result of line 2

#BigMatrix( -- result of line 3, contents of bm2

[4.00,6.00],

[4.00,9.00]

)

#BigMatrix( -- result of line 4, contents of bm1

[0.75,-0.50],

[-0.33,0.33]

)

#BigMatrix( -- result of line 5, contents of bm2

[0.75,-0.50],

[-0.33,0.33]

)


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 Viewport Drawing Methods.

Constructors

Box2 <x_integer> <y_integer> <w_integer> <h_integer>

Constructs a Box2 with the upper left corner at [x,y] with width w and height h.

Box2 <upperleft_point2> <lowerRight_point2>

Constructs a Box2 object from the specified corners.

Properties

<Box2>.x : Integer

<Box2>.y : Integer

<Box2>.w : Integer

<Box2>.h : Integer

<Box2>.left : Integer, alias of x property

<Box2>.right : Integer

<Box2>.top : Integer, alias of y property

<Box2>.bottom : Integer

<Box2>.center : Point2, read-only

The right property is calculated as right = x + w – 1. The bottom property is calculated as bottom = y + h – 1. Setting the right or bottom property will normally change the w and h properties, respectively. However, if right is set less than left, the right and left values will be swapped, and then the new value will be used as the left value. Likewise, if bottom is set less than top, the bottom and top values will be swapped, and then the new value will be used as the top value.

Operators

<Box2> == <Box2>

<Box2> != <Box2>

Standard comparison operators. Two Box2 values are equal if all of their component values are equal.

Methods

scale <Box2> <float>

Scales the coordinates of the box about the center of the box.

translate <Box2> <point2>

Translates the coordinates of the box by the distance specified.

contains <Box2> <point2>

Determines if the point2 value is contained within the Box2. Returns true if the point is inside the Box2 or on the Box2 edge; otherwise false.

rectify <Box2>

Adjusts the coordinates of the box such that top < bottom and left < right.

empty <Box2>

Sets the Box2 to a special "empty" value.

isEmpty <Box2>

Returns true if the Box2 contains the special "empty" value, false otherwise.


Time Data Values

The Time data value types are:

Time Values

Interval Values


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.

Literals

[-]{<decimal_number>[m | s | f | t]}+ -- minutes/sec/frames/ticks

[-]{<digit>}:{<digit>}[.{<digit>}] -- SMPTE mins:secs.frame

[-]<decimal_number>n -- active segment normalized time

Example Literals

2.5s -- 2.5 seconds

1m15s -- 1 minute 15 seconds

2m30s5f2t -- 2 minutes 30 seconds 5 frames 2 ticks

125f -- 125 frames

17.25f -- 17.25 frames

1f20t -- 1 frame 20 ticks

2:10.0 -- 2 minutes 10 seconds 0 frames (SMPTE)

0:0.29 -- 29 frames (SMPTE)

Constructor

normTime <float> -- time from normal fraction

Properties

<time>.ticks : Time as ticks

<time>.frame : Time as frames

<time>.normalized : Time as normalized fraction of active segment

Operators

<time> + <time>

<time> - <time>

- <time>

<time> * <number>

<time> / <number>

scale time

<time> == <time>

<time> != <time>

<time> > <time>

<time> >= <time>

<time> < <time>

<time> <= <time>

<time> as <class>

You can coerce a time to a Number - you get the time in ticks.

Methods

random <time> <time>

abs <time>

Examples

sliderTime = 30

t2 = n as time

if currentTime == 45 then ...

Some of the examples above refer to system global variables. See 3ds max System Globals for more details.


Interval Values

An Interval class represents an interval of time. It has two time value components, start and end. The time values can be numbers or Times, numbers being interpreted as frame counts.

Constructor

interval <start_time> <end_time>

Properties

<interval>.start : Time

<interval>.end : Time

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 3ds max System Globals for more details.


Special Data Values

Undefined Value

Ok Value

Unsupplied Value

DontCollect Value


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


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


Bitmap Values

The Bitmap class provides storage of and low-level access to 3ds max bitmaps.

Bitmaps can be temporary objects that are resident only in memory, or they can be associated with a file on disk. Those bitmaps associated with files have a non-null .fileName property and are either load-only or save-only, but not both (this is with respect to file I/O; all bitmaps in memory can have their pixels modified by the setPixel() functions). You make load-only bitmaps with the openBitmap() and selectBitmap() functions. You make temporary or save-only bitmaps with the bitmap() constructor, or with the render(), copy(), or getChannelAsMask() functions. To make them savable, they must have a valid file name, supplied either on the constructor with a fileName: parameter or by setting the .fileName property.

Constructors

bitmap <width <height> [ filename:<filename_string> ] \

[ numframes:<integer> ] \

[ color:<color> ] \

[ gamma:<float> ] \

[ pixelAspect:<float> ]

Creates an empty bitmap. The bitmap value returned is a savable bitmap.

The filename: parameter allows you to set the name of the file the bitmap will be saved to using the save method. Specifying an existing bitmap file name does not load the contents of the bitmap file into the bitmap value.

The numframes: parameter allows you to create a multi-frame bitmap.

The color: parameter allows you to set the initial color of all pixels in the bitmap. For example:

b = bitmap 320 240 color:white

The gamma: parameter allows you to set the gamma for the newly created bitmap. For example:

b = bitmap 320 240 gamma:1.9

render camera:c to:b

The pixelAspect: parameter allows you to set the pixel aspect for the newly created bitmap.

Note that it is not possible to change the gamma or pixel aspect of a bitmap once created, though you can copy one bitmap into a newly created one that has a different gamma or pixel aspect to achieve this effect.

openBitMap <filename_string>

Returns a bitmap value containing the contents of the specified bitmap file. If the specified bitmap file does not exist, a runtime error is generated. The bitmap value returned is a load-only bitmap.

selectBitMap [ caption:<open_dialog_title_string> ]

This method displays a Image Input selection browser for the user to select a bitmap file. Returns a bitmap value containing the contents of the selected bitmap file, or the value undefined if the user presses Cancel in the browser. The bitmap value returned is a load-only bitmap.

copy <bitmap>

Copies an existing bitmap, creating an unique instance of the bitmap. If the source bitmap is load-only, the bitmap value returned is a temporary bitmap value, with a null filename and just one frame. If the source is a multi-frame file, it snaps the current frame into the new copy, which becomes frame 0.

Properties

<bitmap>.filename : String

Lets you get or set the file name associated with the bitmap.

<bitmap>.palette : Array

Yields an array of 256 colors (a bug in the current 3ds max SDK prevents working with paletted files of other than 256 entries). Take care accessing this array with colors indexes retrieved by the getIndexedPixels() function described below, because these indexes are 0-based and MAXScript array indexes are 1-based. Yields undefined if the bitmap is not paletted. Currently you cannot create a paletted bitmap in MAXScript, however you can read and write to a pre-existing paletted bitmap.

<bitmap>.frame : Integer

Get and set the current frame number in a multi-frame file. Setting this property is permitted only on load-only bitmaps. The frame number is 0-based for inherently multi-frame files, such as .avi and .mov.

<bitmap>.numframes : Integer

The number of frames in a multi-frame file, yields 1 for a single image file.

<bitmap>.height : Integer, read-only

Returns bitmap's height in pixels.

<bitmap>.width : Integer, read-only

Returns bitmap's width in pixels.

<bitmap>.gamma : Float, read-only

Returns bitmap's gamma value.

<bitmap>.aspect : Float, read-only

Returns the bitmap's pixel aspect. Note that this is the aspect of the pixel, not the aspect of the bitmap image.

Methods

display <bitmap>

Opens a virtual frame buffer (VFB) displaying the image. Changes to the bitmap are not automatically displayed to the VFB. To update the VFB, you need to call this function again. Setting the frame property does cause the VFB to update. Each bitmap has its own VFB, i.e., if you display two different bitmaps, two VFBs will be displayed.

unDisplay <bitmap>

Close the VFB associated with the bitmap if open.

save <bitmap> [frame:<integer>]

Saves current state of the bitmap. Make sure the file name has been set first. When saving multi-frame image files, the effect of the frame: keyword parameter is different depending on the type of output file. Inherently multi-frame files, such as .avi and .mov, ignore the frame: parameter and always write to the next output file frame in sequence on each save(); you cannot randomly write frames or rewrite frames already saved. Saving image sequences (such as .bmp, jpg, .tga) requires supplying the frame: parameter and causes the frame number to be appended to the output file name for each frame saved. This effectively generates a sequence of image files suitable for building an IFL. The output file remains open until you call close on the bitmap.

The save() function can only be called on a savable bitmap. You will get a runtime error if you attempt to save a bitmap opened with openBitmap() or selectBitmap().

close <bitmap>

Closes the bitmap file associated with the bitmap if it is open for output. A bitmap file is opened for output when you call save on the bitmap value the first time. If a VFB associated with the bitmap is open, it will be closed. This function also frees all memory allocated by the bitmap, including the internal pixel frame buffer. If you are generating many bitmaps, say in a rendering loop, you can use the close() function to free these often large amounts of memory, that won't otherwise be released until the next garbage collection.

copy <source_bitmap> <dest_bitmap>

Copies the source bitmap to the destination bitmap. If the size of the two bitmaps is different, the image will be scaled to fit the destination bitmap.

gotoFrame <bitmap> <frame>

Position multi-frame file (avi, flc, etc.) to frame frame. This method is permitted only on load-only bitmaps. The frame number is 0-based for inherently multi-frame files, such as .avi and .mov. Updates VFB if open.

getPixels <bitmap> <coord_point2> <num_pixels>

Retrieve a sequence of pixels from a row in the bitmap as an array of color values. The coord_point2 argument specifies the starting pixel coordinate with [0,0] at the top-left-hand pixel. The .x component of the Point2 coordinate is the column, and the .y component is the row. The sequence must come from one row only; you cannot retrieve a sequence of pixels that spans multiple rows. Using any out of-bounds coordinates or retrieving over row boundaries will fail and yield an empty array.

setPixels <bitmap> <coord_point2> <color_value_array>

Sets the sequence of pixels in a row in the bitmap starting at the Point2 coordinate to the values in the given array. The .x component of the Point2 coordinate is the column, and the .y component is the row. The number of pixels to set is taken from the size of the array. As with getPixels(), you cannot set pixel sequences across a row boundary.

getIndexedPixels <bitmap> <coord_point2> <num_pixels>

Retrieve a row of pixels as an array of palette index numbers. The coord_point2 argument specifies the starting pixel coordinate with 0,0 at the top-left-hand pixel. The index numbers are origin 0. Note that this is in keeping with indexed color conventions but not MAXScript's. Take care accessing any retrieved palette array using these numbers because the retrieved palette is returned as a MAXScript array and these arrays use 1-based indexes. You cannot get pixels sequences that cross row boundaries.

setIndexedPixels <bitmap> <coord_point2> <number_array>

Sets the row of pixels starting at the Point2 coordinate to the color indexes in the given array. The number of pixels to set is taken from the size of the array. The color indexes are zero-based. You cannot set pixels sequences that cross row boundaries.

getChannel <bitmap> <coord_point2> <chan_name>

Retrieves the g-buffer channel data for the named channel for the pixel specified by 2D coordinate. The chan_name argument specifies the channel identifier, chosen from the following:

#zDepth

#matID

#objectID

#UVCoords

#normal

#unClamped

#coverage

#node

#shaderColor

#shaderTransparency

#velocity

#weight

If the bitmap contains the requested channel, the returned value is always an array of values, one for each layer present in the channel at that pixel, ordered from front to back. If the bitmap does not contain the requested channel, the function returns the value undefined. Typically, you get bitmaps containing channels by opening .rla files or using the MAXScript render() function with the channels: parameter supplied. You will get multiple values in the array if the front objects have any transparency. For example:

getChannel bm [x,y] #zDepth

might return:

#(-354.413, -354.467, -355.271, -1e+030)

indicating there is a front surface with non-zero transparency at depth -354.413, another at -354.467 and a final one at -355.271. The –1e+30 value represents the background image plane. You could retrieve the #node channel (if it was generated) to get the actual scene objects at those depths, eg:

getChannel bm [x,y] #node

might return:

#($Sphere:Sphere02 @ [-4.7,24.3,0.0], $Sphere:Sphere02 @ [-4.7,24.3,0.0],$Sphere:Sphere01 @ [-8.3,56.2,5.7])

The type of values returned in the array depend of the channel, as follows:

#zDepth : <float>

#matID : <integer>

#objectID : <integer>

#UVCoords : <point2>

#normal : <point3>

#unClamped : <color>

#coverage : <float>

#node : <node>

#shaderColor : <color>

#shaderTransparency : <color>

#velocity : <point2>

#weight : <color>

See the 3ds max Software Development Kit Help file for information on the data stored in the g-buffer channels.

getChannelAsMask <bitmap> <chan_name> [to:<bitmap>] \

[fileName:"filename_string"] [pixelAspect:<float>] \

[gamma:<float>] [layer:<integer>] [invert:<boolean>] \

[node:<node> | objectID:<integer> | matID:<integer>] \

[velocity:#angle | #magnitude] | [angle:<float>]

Builds and returns a separate 8-bit gray-level bitmap, suitable for use as a mask in materials, maps, effects, and so on. This bitmap corresponds roughly to the display you see in the visual frame buffer if you select a g-buffer channel to view. In addition, you can cause this mask to be masked itself to a selected node, object ID or material ID. The parameters are as follows:

<bitmap>

The source bitmap containing the source g-buffer channel data.

<chan_name>

The channel from which to generate a mask. The chan_name values are as described for the getChannel() method. Note that the mask is a single 8 bit value while the channel may be a complex value of some kind. In each case, a mapping to 8 bits is performed. Unless noted differently below, this mapping is the same mapping as in used by 3ds max to generate monochrome images in the Virtual Frame Buffer.

to:<bitmap>

Specifies an existing bitmap to write the mask into. Its width and height must match the source bitmap.

fileName:"filename_string"

Specifies the file name associated with the generated bitmap.

gamma:<float>

Specifies the generated bitmap's gamma value.

pixelAspect:<float>

Specifies the generated bitmap's pixel aspect. Note that this is the aspect of the pixel, not the aspect of the bitmap image.

layer: <integer>

Specifies the channel layer of the source bitmap to extract data from. Defaults to 1.

invert:<boolean>

If true, inverts the generated bitmap. Defaults to false.

node:<node>

objectID:<integer>

matID:<integer>

Specifies a sub-mask. If one of these parameters is supplied, the generated mask is clipped to contain data only in pixels where the given node, objectID or materialID is visible. To use this sub-masking, you must ensure the #node, #objectID or #matID channel is present in the source bitmap. Further, if the #coverage channel is present in the source bitmap, the sub-mask is anti-aliased by the coverage data.

velocity:#angle | #magnitude

angle:<float>

These parameters can only be specified if the selected channel is #velocity. The default velocity parameter value is #magnitude. These parameters control the generated bitmap as follows:

velocity:#angle

Generated bitmap pixel values are proportional to angle of pixel movement direction, with an angle of direction of 0 degrees (horizontal to the right) mapping to a luminance value of 0, 180 degrees mapping to a luminance value of 127, and 360 degrees mapping to a luminance value of 255.

velocity:#magnitude

Generated bitmap pixel values are proportional to velocity magnitude. High velocities are darker than low velocities.

angle:<float>

Generated bitmap pixel values are proportional to movement direction deviation from the given angle, with a luminance value of 255 at the exact angle and falling off to a luminance value of 0 at 10 degrees from the specified angle. The specified angle is relative to 0 being horizontal to the right.

Related Methods

setSilentMode <boolean>

Sets Silent mode on or off. If Silent mode is off, any errors occurring during bitmap input or output will result in an error message dialog being displayed by the 3ds max bitmap I/O routines. If Silent mode is on, error message dialogs are not displayed. Returns a boolean signifying the prior Silent mode state.

The Silent mode state is an internal 3ds max state, and other 3ds max plug-ins can turn this state on or off. It is recommended that if you use this method that you turn the state on or off saving the return value, perform the bitmap input or output, and then restore the state to its original value.

silentMode()

Returns a boolean signifying the Silent mode state.

selectSaveBitMap [ caption:<open_dialog_title_string> ]

Displays a 3ds max bitmap save dialog and returns the fully-specified file path name as a string. Returns undefined if the user cancels out of the bitmap save dialog.

freeSceneBitmaps()

Frees up all the memory used by the image file bitmap caches. This is useful if memory is fragmented with a lot of different bitmaps and you want to have just the ones currently active reloaded.

getBitmapOpenFileName caption:<title> filename:<seed_filename_string>

getBitmapSaveFileName caption:<title> filename:<seed_filename_string>

Displays the bitmap file selection dialog. Both functions return a fully-specified file path name or undefined

if the user cancels out. If an existing file name is selected using the getBitmapSaveFileName() function, a File

Exists/Confirm Overwrite dialog will be displayed. Note: The getBitmapOpenFileName() function does not require

that an existing file name be selected - i.e., a file name is returned if the user types a file name that does not

exist. If necessary, you should check the file name that is returned to ensure the file exists.

Notes

When you open a bitmap file, an entire frame is loaded into memory. When you are finished processing a bitmap, it is a good idea to either call close() on the bitmap or assign the value undefined to the variable storing the bitmap value, and then manually run garbage collection (gc()), so that it's memory can be released. Another technique for conserving memory when using the render() or getChannelAsMask() functions repeatedly is to use the to:<bitmap> keyword argument which allows those functions to overwrite an existing bitmap's pixel image with the new rendering or mask.

There currently is no access to the properties associated with the bitmap output plug-ins. This means that you cannot set the codec used for .avi files, nor the setup parameters for .rla and .tga files. The properties used are the properties that were last used when saving that file type in 3ds max.

Examples

The following script shows how to properly create and save a multi-frame image file.

Script

theTeapot=teapot() -- something to render

animate on at time 10 \ -- set animate and time context

rotate theTeapot 180 z_axis -- rotate the teapot

cam=targetcamera pos:[200,0,100] \ -- camera pointed at teapot

target:theTeapot

renderFrames=#{1,3,5..12} -- specify frames to render

b=bitmap 160 120 filename:"c:\\t.avi" -- create a new bitmap

for i = 1 to renderFrames.count do -- loop though renderFrames

(

if renderFrames[i] then -- if supposed to render frame...

(

at time i -- set time context

render 160 120 camera:cam to:b -- render to bitmap frame

save b -- save each frame as you advance

) -- if you save AFTER the loop,

-- just the last frame is saved.

)

close b -- close the output file. This will

-- also get rid of the reference to

-- the bitmap value and free its

-- memory.

Output

$Teapot:Teapot01 @ [0,0,0] -- result of line 1

OK -- result of lines 2 and 3

$Target_Camera:Camera01 @ [200,0,100] -- result of lines 4 and 5

#{1, 3, 5..12} -- result of line 6

BitMap:c:\t.avi -- result of line 7

OK -- result of for loop, lines 8 to 15

OK -- result of line 16

The following script reads a bitmap file, and outputs a script to Listener that implements a function that will recreate the same bitmap. This function can then be copied into your script. This is useful for building button images in MAXScript, so that you don't need to distribute bitmap files along with your script.

Script

(

b=selectbitmap() -- open image file browser

bname="bitmap_"+(getfilenamefile b.filename) -- build name from filename

w=b.width -- get properties of bitmap

h=b.height

format "----------\nfn load_% = (\n" bname -- start defining function

format "local %=bitmap % %\n" bname w h -- create bitmap in function

-- write out a function that unpacks an integer into a pixel color

format "fn unpack val = for p in val collect (r=p/256^2; g=p/256-r*256; b=mod p 256; color r g b)\n"

for r=0 to h-1 do -- for each row in the bitmap

-- have function write the column of pixels to the bitmap

( format "setpixels % [0,%] (unpack #(" bname r

pixels=getpixels b [0,r] w -- read in the column of pixels

for c=1 to w do -- loop through each pixel

( p=pixels[c] -- get the pixel

-- pack the pixel into an integer and write it out

format "%" (((p.r as integer)*256+(p.g as integer))*256+(p.b as integer))

if c != w then -- if not at end of data

format ", " -- write a comma

else

format "))\n" -- else close out the line

)

)

format "return %\n" bname -- function returns the bitmap

format ")\n----------\n" -- finish off function definition

)

Output

----------

fn load_bitmap_convert = (

local bitmap_convert=bitmap 4 4

fn unpack val = for p in val collect (r=p/256^2; g=p/256-r*256; b=mod p 256; color r g b)

setpixels bitmap_convert [0,0] (unpack #(12632256, 12632256, 12632256, 12632256))

setpixels bitmap_convert [0,1] (unpack #(255, 255, 255, 255))

setpixels bitmap_convert [0,2] (unpack #(255, 255, 255, 255))

setpixels bitmap_convert [0,3] (unpack #(255, 12632256, 12632256, 12632256))

return bitmap_convert

)

----------

Also see the example in Point3 Values 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

StringStream Values

WindowStream Values


FileStream Values

A FileStream class implements text file input and output in MAXScript. A FileStream value represents an open text file in MAXScript. Text file I/O is performed by calling functions on the FileStream value.

Constructors

createFile <filename_string>

creates a new file and returns a <filestream> value. If the specified file cannot be created, the value undefined is returned.

openFile <filename_string> [ mode:<mode_string> ]

opens an existing file and returns a <filestream> value. If the specified file does not exist, the value undefined is returned. The optional mode_string can be "a" to mean open an existing file for append output, or "r" to mean open file read-only.

openEncryptedFile <filename> <key>

opens the encrypted file using the given integer key and returns a FileStream value that you can then do read calls on, exactly as you can on FileStreams returned from the openFile() function. See Encrypted Files for details on encrypted files.

Methods

readLine <filestream>

read next line, return as string

readChar <filestream>

read next char, return as string

readChars <filestream> <char_count>

reads the specified number of characters and returns them in a string.

readDelimitedString <filestream> <string>

takes a delimiter character (as a string) and reads in characters until the delimiter is found (or end-of-file is reached) and returns the characters in a string.

skipToString <filestream> <string>

takes a character string and scans forward in the file until it finds an occurrence of the string and positions the file just after that string. If the string is not found, the function returns the value undefined.

skipToNextLine <filestream>

positions the input file at the beginning of the next line

filePos <filestream>

retrieve the current offset into the file

seek <filestream> <integer>

position the file at the given offset so that subsequent I/O will start there.

eof <filestream>

return true if there is no more data in the file, false otherwise.

flush <filestream>

ensure all output to file is on disk, flushes the memory buffers.

close <filestream>

flushes the memory buffers and closes the file

For the following methods, see the description of the execute() method in String Values for information on the scope of variables used in the evaluated expressions.

readValue <filestream>

read and evaluate the next MAXScript <operand> from the file

readExpr <filestream>

read and evaluate the next MAXScript <expr> from the file

execute <filestream>

read and evaluate all the expressions left in the file.

The differences between the above methods can be seen in the following example. In this example, a stringstream value is created that contains a string containing two expressions – random 0. 1. and random red blue. The readValue, readExpr, and execute methods are then used with the stringstream as the argument.

Script

s=stringstream "random 0. 1.;random red blue"

readvalue s -- read and evaluate the first value

readvalue s -- read and evaluate the second value

seek s 0 -- position at beginning of stringstream

readexpr s -- read and evaluate the first expression

readexpr s -- read and evaluate the second expression

seek s 0 -- position at beginning of stringstream

execute s -- evaluate all expressions

Output

StringStream:"random 0. 1.;random red blue" -- result line 1

random() -- result line 2 (evaluated "random")

0.0 -- result line 3 (evaluated "0.")

OK -- result line 4

0.448042 -- result line 5 (evaluated "random 0. 1.")

(color 86.476 0 163.24) -- result line 6 (evaluated "random red blue")

OK -- result line 7

(color 30.2417 0 143.636) -- result line 7 (evaluated all expressions,

-- returns result of last expression)

Associated Methods

print <value> to: <filestream>

format <fmt_string> { <value> } to: <filestream>

See Value Common Properties, Operators, and Methods for a description of these methods.

See also

External File Methods

File Name Parsing

Standard Open and Save File Dialogs


StringStream Values

The StringStream class allows you to construct and parse strings using all the text file I/O functions. For example, you can set up a StringStream and build it up by performing prints and formats to it, just as you would to a text file. Conversely, you can convert a String into a StringStream and then work through it using functions like readLine(), readValue(), skipToString(), etc. Since Strings are easily converted to and from StringStreams, this is often a convenient way to work on large, complex strings.

The StringStream class can be used in conjunction with the AppData accessing functions for storing and retrieving large and complex amounts of script-generated data permanently within a 3ds max scene file.

Constructors

stringStream <initial_string>

<string> as stringStream

convert existing String to StringStream.

See also String Literals and String Values.

Operators

<stringstream> as string

convert StringStream to a String

Methods

copy <stringstream>

create a separate copy of the StringStream

Associated Methods

print <value> to:<stringstream>

format "<fmt_string>" {values} to:<stringstream>

The print() and format() functions provide a way to build up a StringStream a piece at a time. As with text file output, each call to print or format appends to existing text, the StringStream dynamically grows as needed. Note that you can reposition output streaming using the seek() function documented below.

The following functions are identical to the text file input functions available for text FileStream values. See the FileStream Values class documentation for details. When called on StringStream instances, they read progressively through the string extracting successive values and lines and characters, etc.

readValue <stringstream>

readExpr <stringstream>

readLine <stringstream>

readChar <stringstream>

readChars <stringstream> <number>

readDelimitedString <stringstream> <string>

skipToString <stringstream> <string>

skipToNextLine <stringstream>

execute <stringstream>

filePos <stringstream>

seek <stringstream> <pos>

eof <stringstream>

close <stringstream>

flush <stringstream>

The close() and flush() functions are provided for consistency with file I/O but are not necessary for StringStreams and do nothing if called.


WindowStream Values

The WindowStream class allows you to output strings to a script Editor window. This is useful for directing output to a separate window for ease of inspection, editing, or later saving to a file.

Constructors

newScript()

Opens an empty script Editor window and returns a WindowStream value.

Associated Methods

print <value> to:<windowstream>

format "<fmt_string>" {values} to:<windowstream>

Output to a WindowStream is inserted at the current cursor position in that window.

Notes

When using the format() function with a WindowStream, a new line in the Editor window is not displayed until an end-of-line character ("\n")is output.

Examples

debug = newScript()

...

print $foo to:debug

...

format "name is %\n" obj.name to:debug


MAXKey Values

Certain controllers (keyframeable controllers) store their animation values as keys. As seen by MAXScript, keys are stored in a MAXKeyArray. The MAXKeyArray for a keyframeable controller is accessed via the .keys property of the controller.

For more information on MAXKeyArrays, see MAXKeyArray Values.

See also

MAXKey Common Properties, Operators, and Methods

Working with MAXKey Values


MAXKey Common Properties, Operators, and Methods

Constructor

addNewKey <controller> <time> [ #select ] [ #interpolate ]

Adds a new key to the controller track at the time specified. The new key is also selected in the track view if the #select optional argument is specified. The value for the new key is taken from the previous key, unless the #interpolate argument is specified in which case the value is the interpolated controller value at that time.

getKey <controller> <index_integer>

Returns the indexed key as a MAXKey instance.

<key_array>[<index_integer>]

where <key_array> is:

<controller>.keys

<node>.<animatable_property>.keys

Properties

For keys associated with all keyframeable controller types, the following properties are accessible:

<key>.time Time -- time value or number (interpreted as frames)

<key>.selected Boolean -- specifies whether the key is selected. Read/write access.

The .time property is read-only for the keys for some controllers, and read/write for the keys of other controllers. The controller type description specifies whether the .time property is read-only or read/write. For controllers where the key .time property is read/write, the following properties are also available:

<key>.value varies -- class determined by its containing controller

Methods

copy <key>

Creates a copy of the key value. This copy is not independent of the original key, as a key value always references a key in a controller. This method exists primarily to support copying of arrays.

The keys on Bézier, TCB, and Barycentric Morph controllers have additional properties and methods. See Bezier Controller Keys, TCB Controller Keys, and Barycentric Morph Controller Keys for details.

See also

MAXKeyArray Values

Controller Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Working with MAXKey Values

Changing the .time property of a key may cause it to go out of time order relative to the other keys in the controller. You must call the sortKeys() function on the controller or associated MAXKeyArray once all key time manipulations of this kind is complete so that animation will perform correctly.

The class of a key's value property is determined by the controller it is in, for example, a linear_float key has a float .value, a tcb_rotation key has a quaternion .value, etc. The properties are all settable and support the math-assignment operators and nested-property access. Here are some examples:

$foo.pos.keys[2].time += 20f -- change time of single key

$foo.pos.keys.time += 20f -- change time of all keys

$box1.uvw_map.center.keys[2].value.x += 20

for k in $baz.bend.angle.keys do k.value *= 1.1

In some cases, the actual value stored in a key is not the value shown in the command panels, shown in Track View, the value returned by the .value property of the key, or the value returned when accessing the property to which the key's controller is assigned. Instead, a scaling factor is applied to the key's value before the value is made "visible". For example, percentages are normally displayed with a range of 0-100, rotation angles are in degrees, colors are [0-255,0-255,0-255]. The unscaled key values for percentages are normally in a range of 0-1, rotation angles in radians, and colors are [0-1,0-1,0-1].

In the description of properties for each class, the scaling factor, if any, is identified for each property. Take for example the following properties for the PArray class:

<PArray>.X_Spin_Vector Float default: 1.0 -- animatable

<PArray>.Spin_Time_Variation Float default: 0.0 -- animatable, percentage

<PArray>.Spin_Phase Float default: 0.0 -- animatable, angle

<PArray>.viewPercent Float default: 10.0 -- percentage

The .X_Spin_Vector property does not apply any scaling to its controller keys. The .Spin_Time_Variation property applies percentage scaling to its controller keys (displayed as percentage, stored as fraction). The .Spin_Phase property applies angle scaling to its controller keys (displayed as degrees, stored as radians). The .viewPercent property is stored internally with a percentage scaling factor, but since this property is not animatable, this scaling it invisible to MAXScript.

Normally this scaling is not of concern when programming in MAXScript, but there are two cases where it must be taken into account. The first is when using script controllers, and is described in Script Controllers.

The second case is when one controller is applied as the controller for two or more properties. The scaling is an attribute of the animatable property, not the controller, so in (the admittedly rare) situations in which a controller is shared by several animatables that have different scaling, unexpected results will occur if you do not take into account the scaling factor. An example of this is shown in the following script, where the same controller is shared between three differently scaled properties.

Script

obj=PArray()

cont=bezier_float()

obj.X_Spin_Vector.controller=cont

obj.Spin_Time_Variation.controller=cont

obj.Spin_Phase.controller=cont

obj.X_Spin_Vector=1

obj.X_Spin_Vector -- no scaling

obj.Spin_Time_Variation -- percentage

obj.Spin_Phase -- angle

Output

$PArray:PArray03 @ [0,0,0] -- result line 1

Controller:Bezier_Float -- result line 2

Controller:Bezier_Float -- result line 3

Controller:Bezier_Float -- result line 4

Controller:Bezier_Float -- result line 5

1 -- result line 6

1.0 -- result line 7, unscaled

100.0 -- result line 8, percentage scaled, 1 = 100%

57.2958 -- result line 9, angle scaled, 1 radian = 57.2958 degrees

If you do assign the same controller to properties with different scaling factors, you should take care to access the .value property through the correct animatable property - this provides a scaling context for the access operation.


ArrayParameter Values

Certain plug-ins in 3ds max store parameter data in a form that is accessible by MAXScript as ArrayParameters. As such, you can access the parameter data by index and iterate over the parameter data.

Constructors

<MAXWrapper>.parameter

Where the parameter contains an ArrayParameter.

Properties

<ArrayParameter>.count

Returns the number of values in the ArrayParameter. Read-only in most cases, with exceptions noted in the MAXWrapper object description where an adjustable ArrayParameter is used.

Operators

<ArrayParameter>[<integer>]

Returns element of ArrayParameter. Indexes start at 1.

<ArrayParameter>[<integer>] = <value>

Sets element of ArrayParameter to value.

Notes

Each ArrayParameter can only contain data of a certain type (for example, Float), or a controller that matches that data type. The showProperties() function indicates these array parameters as <type> array, for example, int array, texmap array, etc.

A plug-in can also define parameter names which point to specific entries in one of its ArrayParameters. For example, mapAmounts is a property of Standard materials containing an ArrayParameter. Each element in this ArrayParameter contains the map amount for one of the map channels. For easier access in a script, the Standard .ambientMapAmount property is provided as an alias for mapAmounts[1] (along with aliases for all the other common maps). You can access the controller for the ambientMapAmount alias either via the .controller property on the alias or on the .mapAmounts[1] property. For example, either:

$foo.material.ambientMapAmount.controller

or

$foo.material.mapAmounts[1].controller

will gets the controller on the ambient map amount material property.

Examples

The following script shows the use of showProperties() to show the data type for elements of ArrayParameters, access to ArrayParameter elements, and a case of a plug-in defining parameter names which point to a specific entry in one of its ArrayParameters.

Script

m=CompositeMaterial() -- create a Composite material

showproperties m -- show the properties for the material

m.amount -- show value of parameter amount

m.amount[1] *= .5 -- reduce the value for one element

m=standard() -- create a Standard material

showproperties m -- show it's properties

m.ambientMapAmount=13 -- set the value for one element via its alias

m.mapAmounts[1] -- and show the element was changed

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


Collections

Many of the values you work with in MAXScript are sequenced collections, notably arrays, wild-card pathname selections, and the built-in object sets. In the manner of most operating system shell command languages, MAXScript will automatically apply appropriate operations to each of the members in these target collections.

Examples

hide $lights/key* -- hide all the 'key' lights in the scene

$box*.position = [0,0,0] -- recenter all boxes

delete dead_objects -- delete all the objects in the array

-- 'dead_objects'

obj.pos.keys.intangent=#fast -- set in tangent to fast for all obj's position keys

lights.value *= 0.8 -- turn down all the lights 20%

MAXScript determines whether to perform a mapped operation by looking at the first argument to a function or the target in a property assignment to see if it is a sequenced collection. In the case of a function call, it also looks to see if the function is of the appropriate kind, evaluates all the other argument expressions once only. MAXScript then calls the function on each of the members of the first argument collection passing along the other evaluated arguments. In the case of a property assignment, it evaluates the right-hand-expression once only and assigns the value to the named property of each of the elements in the target value collection.

This means that every element in the collection must be a valid target for the function or have the named property in question. If MAXScript comes across an inappropriate target it will report an error and stop the automatic operation.

Except for certain common properties, MAXScript currently only allows automatic collection mapping of property assignment one level deep. For example, the following will perform collection mapping across the objects ObjectSet:

objects.pos = [0,0,0] -- move all objects to world center

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.

As described in For Loop, 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

PathName Values

ObjectSet Values

SelectionSet Values

SelectionSetArray Values

NodeChildrenArray Values

VertexSelection Values

FaceSelection Values

EdgeSelection Values

KeyArray Values

MAXNoteKeyArray Values

ModifierArray Values

MaterialLibrary Values

NURBSSet Values


Array Values

An array is a variable length indexable sequence of values. The values in an array can be of any type. Array values are mappable.

Literals

#(<value>, <value>, ...)

#() -- an empty array

See also Array Literals.

Constructors

<collection> as array

Convert collection to an array.

Properties

<array>.count : Integer, read-only

Returns number of elements in array.

Operators

<array>[<integer>]

Returns element of array. Indexes start at 1.

<array>[<integer>] = <value>

Sets element of array to value, growing array as necessary.

<array> + <collection>

Like join except a completely new array is constructed containing all the elements of the first and second operands

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

Methods

append <array> <value>

Append value to array, growing it as necessary.

copy <array> [#noMap] -- mapped

Creates a copy of all the elements in the array. Returns a value of OK. If #noMap is specified, the copy made is what is called a shallow copy - only a copy of the upper-level value itself (that is, the array value) is created. Copies aren't made of values stored in the array, rather a reference to the same value is stored in both array values.

deleteItem <array> <number>

Delete element indexed by number from array, shrinking it in size by 1.

join <array> <collection>

Appends all the elements of the second argument to the array (first) argument.

sort <array>

Sorts the elements of the array into ascending order. All the elements must be comparable.

findItem <array> <value>

Does a MAXScript '==' comparison between elements in the array and the target object and then returns the index of the first occurrence of the given value in the array or zero if the value is not in the array.

Values such as Point3s and Strings match if they have the same contents.

insertItem <value> <array> <integer>

Inserts the value at the specified index in the array, growing the array if necessary

qsort <array> <function> [start:<integer>] [end:<integer>] [user-defined key args passed to function]

Sorts the array using the specified function for element-by-element comparison. The comparison function must take 2 values as arguments, and return a number < 0 if the first value is less than the second 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))

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 or no 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 or no arguments are specified, the value undefined is returned.

Note: As described in Reference Assignment, the elements in an array are stored by reference rather than by value. When you operate directly on array elements, and the reference to the array is stored in more than one place, unexpected results may occur. An example of this is shown in the following script.

Script

RandomSets=#() -- create array

RandomSet=#() -- create array

for i=1 to 3 do -- loop i

( for j=1 to 3 do -- for each i loop j

RandomSet[j]=random 1 100 -- set array element to random value

print RandomSet #nomap -- print array of random values

RandomSets[i]=RandomSet -- store random value array in array

)

print RandomSets -- print array of arrays of random values

Output

#() -- result of line 1

#() -- result of line 2

#(33, 47, 31) -- output from line 6, i=1

#(4, 52, 39) -- output from line 6, i=2

#(52, 36, 23) -- output from line 6, i=3

OK -- result of for loop, lines 3 to 8

#(52, 36, 23) -- 3 lines of output from line 7

#(52, 36, 23)

#(52, 36, 23)

OK -- result of line 9

As can be seen in the output lines 7 to 9, all the elements of array RandomSets contain the same values, which is not the result as expected from the output shown on lines 3 to 5. The reason the same values are stored in each element of RandomSets is only one array value is actually ever created for RandomSet (in line 2), and line 5 of the script is only changing the elements of that array value. Thus each element of RandomSets is actually pointing at the exact same value. The easiest fix for the above script is to move line 2 into the for i loop expression, thereby creating a new array value which will then be stored in RandomSets.

Script

RandomSets=#()

for i=1 to 3 do

( RandomSet=#() -- create a new array value for RandomSet

for j=1 to 3 do

RandomSet[j]=random 1 100

print RandomSet #nomap

RandomSets[i]=RandomSet

)

print RandomSets

Output

#()

#(89, 27, 88)

#(87, 87, 10)

#(74, 27, 64)

OK

#(89, 27, 88)

#(87, 87, 10)

#(74, 27, 64)

OK

You can convert object sets and wild-card pathnames to arrays using the as operator. This has the effect of taking a "snapshot" into the array of the current objects in the set or those matched by the pathname, so that you can then later work on that collection of objects without worrying if the set or match has changed. This is similar to named selection sets in the 3ds max user interface, and can be used, for example, to keep track of selections as you work interactively with MAXScript. If the user deletes from the scene any of the objects in the array, you will get an error if you try to map operations over the array.

Examples

sel1 = selection as array

boxes_at_load = $box* as array

snap_children = $torso...* as array

original_cameras = cameras as array


PathName Values

PathNames provide the mechanism for naming objects in the 3ds max scene. See also Pathname Literals. Pathname values are mappable.

Example Literals

$box01

$torso/left_upper_arm/left_lower_arm

$*box*

$torso/*

$torso...*

Properties

<pathname>.center : Point3, read-only

Returns center of bounding box of all objects in pathname.

<pathname>.max : Point3, read-only

Returns maximum corner of bounding box.

<pathname>.min : Point3, read-only

Returns minimum corner of bounding box.

<pathname>.count : Integer, read-only

Returns number of objects in set. This property is only valid for wild-carded pathnames, i.e., a pathname that could contain more than one scene object.

Operators

<pathname>[<integer>] -- accesses member of collection. Indexes start at 1.

<pathname> as array -- converts pathname collection to an array

Associated Methods

isDeleted <MAXWrapper_object>

This function yields the result true if the object has been deleted and false if it still exists in the scene. Using the function only makes sense in situations where references to 3ds max objects are held in variables or arrays or passed as parameters and you want to determine whether the object has been deleted from the scene. Performing an operation on a deleted 3ds max object referenced in a variable or array otherwise generates an exception. Any kind of 3ds max object can be tested in this way, scene objects, modifiers, controllers, materials, etc.

Example:

myBoxes = $box* as array -- store list of all boxes in array myBoxes

...

-- <one or more objects in the selection are deleted

-- by the user or other scripts>

...

for obj in myBoxes

where not isDeleted obj do

obj [10,0,0]

Note: The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how 3ds max stores its object hierarchy internally which is affected mostly by order of additions and deletions to and from the scene.

MAXScript lets you set up a 'working level' in the 3ds max scene hierarchy that affects pathnames and coordinate systems and object creation. You do this with a <level_expr>, one of the many context expressions that are described in Context Expressions.

Examples

a = $*feet*[i] -- retrieves the i'th object in the *feet*'s

-- tell me what things inside dummy have a non-identity scale

for obj in $dummy...*

where obj.scale != [1,1,1]

do format "% has non-identity scale: %\n" obj.name obj.scale

-- place $foo's pivot point at the max corner of the set of 'box*' objects.

$foo.pivot = $box*.max

in $dummy

(

sphere name:"ear1" pos:[10,10,10] -- create as children of $dummy

sphere name:"ear2" pos:[-10,10,10]

scale $foo/* [1,1,2] -- looks for 'foo' as a child of $dummy

)


ObjectSet Values

ObjectSets represent the main scene object categories in 3ds max. The "constructors" below are all reserved system variables. ObjectSet values are mappable.

Constructors

objects -- all the objects

geometry -- the standard 3ds max categories...

lights

cameras

helpers

shapes

systems

spacewarps

selection -- the current selection

Properties

<objectset>.center : Point3, read-only

Returns center of bounding box of all objects in set.

<objectset>.max : Point3, read-only

Returns maximum corner of bounding box.

<objectset>.min : Point3, read-only

Returns minimum corner of bounding box.

<objectset>.count : Integer, read-only

Returns number of objects in set.

Operators

<objectset>[<integer>] -- accesses member of collection. Indexes start at 1.

<objectset> as array -- converts objectset collection to an array

Associated Methods

clearSelection()

Clears current scene node selection.

deselect <PathName>

Deselects given node(s). For example:

deselect $box*

deselects all items whose names start with "box".

select <PathName>

Deselects any current selection first, then selects the node(s) you specified.

selectMore <PathName>

Adds the specified node(s) to the current selection.

getCurrentSelection()

Returns the current selection as an array. This is equivalent to selection as array, but can be significantly faster if there are very large numbers of objects in the scene.

Note: 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.

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 SelectionSet Values. 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.

Associated Methods

getNumNamedSelSets()

Returns number of named selection sets as an integer.

getNamedSelSetName <set_index_integer>

Returns name of the indexed named selection set as a string. <set_index_integer> is 1 based.

getNamedSelSetItemCount <set_index_integer>

Returns name of the indexed named selection set as a string. <set_index_integer> is 1 based.

getNamedSelSetItem <set_index_integer> <node_index_integer>

Returns indexed node in the indexed named selection set as a node. <set_index_integer> and <node_index_integer> are 1 based.

Examples

You access an individual selection set by indexing the selectionSets array with its name or index:

set1 = selectionSets["my set 1"]

You can then use that set just as you would use any other object set in MAXScript, such as selection, objects, lights, etc. For example,

move set1 [10,0,0]

moves all the objects in the set across 10 in x.

You can use strings or MAXScript names (starting with #) interchangeably as indexes for the selectionSets array, or you can use an integer as an index if you want to loop over all the sets, for example:

selectionSets[#set2].wireColor = red

for i in 1 to selectionSets.count do

saveNodes selectionSets[i] ("set" + i as string + ".max")

You can change, add and delete new Name Selection Sets by using the standard array methods on the selectionSets array:

selectionSets["new set"] = selection -- snap the current selection

selectionSets["old spheres"] = $sphere* -- all the current objects named

-- "sphere*"

selectionSets[#foo] = #(obj1, obj2, obj3)

deleteItem selectionSets "old set" -- delete the set named "old set"


SelectionSet Values

A SelectionSet represents the named scene node selection sets in the Named Selection Sets drop-down list in the 3ds max toolbar. Also see SelectionSetArray Values. SelectionSet values are mappable.

Constructors

selectionSets[<set_name>] -- set by string or name value

selectionSets[<index>] -- set by order in drop-down list

Operators

<selectionset>[<integer>] -- retrieve nth object in set

Properties

<selectionset>.center : Point3, read-only

Returns center of bounding box of all objects in set.

<selectionset>.max : Point3, read-only

Returns maximum corner of bounding box.

<selectionset>.min : Point3, read-only

Returns minimum corner of bounding box.

<selectionset>.count : Integer, read-only

Returns number of objects in set.

Note: 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 General Node Properties. 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.

<nodechildrenarray>.min : Point3, read-only

Returns minimum corner of bounding box.

<nodechildrenarray>.count : Integer, read-only

Returns number of objects in set.

Operators

<nodechildrenarray>[<integer>] -- retrieve nth child

Methods

append <nodechildrenarray> <node>

Makes the specified node a child of the node NodeChildrenArray was constructed from.

deleteItem <nodechildrenarray> <node>

Removes specified node as a child of the node NodeChildrenArray was constructed from.

Note: 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. The VertexSelection array is dynamic, i.e., its contents will change as the vertices or selected vertices of the mesh node change. VertexSelection values are mappable.

Constructors

<mesh>.selectedVerts -- the currently selected vertices of the mesh object

<mesh>.verts -- all of the vertices of the mesh object, read-only

Properties

<vertexselection>.count : Integer, read-only

Returns the number of vertices in the VertexSelection array.

<vertexselection>.selSetNames : Array of names, read-only

Returns an array of names of the current vertex-level named selection sets for the object the VertexSelection is associated with.

The following properties are present for singleton selections (of the form $foo.verts[n]):

<vertexselection>.index : Integer, read-only

Returns the index of the selected element in the mesh, e.g.,

$foo.selectedVerts[2].index

returns the vertex index of the 2nd vertex in the current selection.

<vertexselection>.pos : Point3

Returns or sets the position of the selected element in the mesh, e.g.,

$foo.verts[i].pos = $baz.verts[j].pos + [10,0,0]

Note that iterating over a selection yields singleton selections in the loop body:

sv = for i in $foo.selectedVerts collect i.index

sv contains selected vertices as array

Operators

<mesh>.selectedVerts = (<array> | <bitarray>)

Selects the specified vertices.

<vertexselection>[<integer>]

Retrieves the indexed vertex as a singleton VertexSelection. Index starts at 1

<vertexselection>[<integer>] = <point3>

Sets the position of the indexed vertex.

<vertexselection>[(<integer_array> | <bitarray>)]

Retrieves the indexed vertices as a VertexSelection. Index starts at 1.

<vertexselection>[(<#name> | <string>)]

Retrieves the vertex-level named selection set, where the name of the named selection set can be specified as a name or string value.

<vertexselection>[(<#name> | <string>)] = (<vertexselection> | <integer_array> | <bitarray>)

Sets the vertex-level named selection set to the specified vertices. The name of the named selection set can be specified as a name or string value, and the vertices can be specified as an array, bitArray, or a VertexSelection from the same object.

Methods

move <vertexselection> <point3>

Moves the vertices in the VertexSelection.

select <vertexselection>

Selects the vertices in the VertexSelection.

deselect <vertexselection>

Deselects the vertices in the VertexSelection.

delete <vertexselection>

Deletes the vertices in the VertexSelection.

append <vertexselection> (<vertexselection> | <integer>)

Appends the vertex or vertices to the VertexSelection.

findItem <vertexselection> (<vertexselection[<integer>] | <integer>)

Returns the selection index of the matching item or 0 if not found. The item is selection index or singleton VertexSelection.

Examples

-- move vertices in 'mouth' named selection set

move $foo.verts[#mouth] [0,0,10]

-- select vertices in 'front verts' set

select $baz.verts["front verts"]

-- set 'baz' named selection set to given vertices

$foo.verts[#baz] = #(1,3,4,5,10)

-- set 'cursel' set to current selection

$baz.verts[#cursel] = $baz.selectedVerts

-- all the names of the vertex-level named selection sets for object $foo

$foo.verts.selSetNames

-- print out all vertex-level named selection sets

for n in $.verts.selSetNames do print $.verts[n]


FaceSelection Values

A FaceSelection represents a set of faces for a scene mesh node as a virtual array. As such, you can access a face by index, iterate over the faces, and apply mapped functions to the faces. See also Editable_Mesh. The FaceSelection array is dynamic, i.e., its contents will change as the faces or selected faces of the mesh node change. FaceSelection values are mappable.

Constructors

<mesh>.selectedFaces -- the currently selected faces of the mesh object

<mesh>.Faces -- all of the faces of the mesh object, read-only

Properties

<faceselection>.count : Integer, read-only

Returns the number of faces in the FaceSelection array.

<faceselection>.selSetNames : Array of names, read-only

Returns an array of names of the current face-level named selection sets for the object the FaceSelection is associated with.

The following property is present for singleton selections (of the form $foo.faces[n]):

<faceselection>.index : Integer, read-only

Returns the index of the selected element in the mesh, e.g.,

$foo.selectedFaces[2].index

returns the face index of the 2nd face in the current selection.

Note that iterating over a selection yields singleton selections in the loop body:

sf = for i in $foo.selectedFaces collect i.index

sf contains selected faces as array

Operators

<mesh>.selectedFaces = (<array> | <bitarray>)

Selects the specified faces.

<faceselection>[<integer>]

Retrieves the indexed face as a singleton FaceSelection. Index starts at 1.

<faceselection>[<integer>] = <point3>

Sets the vertices of the indexed face to the vertex indices specified in the point3 value.

<faceselection>[(<integer_array> | <bitarray>)]

Retrieves the indexed faces as a FaceSelection. Index starts at 1.

<faceselection>[(<#name> | <string>)]

Retrieves the face-level named selection set, where the name of the named selection set can be specified as a name or string value.

<faceselection>[(<#name> | <string>)] = (<faceselection> | <integer_array> | <bitarray>)

Sets the face-level named selection set to the specified faces. The name of the named selection set can be specified as a name or string value, and the faces can be specified as an array, bitArray, or a FaceSelection from the same object.

Methods

move <faceselection> <point3>

Moves the faces in the FaceSelection.

select <faceselection>

Selects the faces in the FaceSelection.

deselect <faceselection>

Deselects the faces in the FaceSelection.

delete <faceselection>

Deletes the faces in the FaceSelection.

append <faceselection> (<faceselection> | <integer>)

Appends the face(s) to the FaceSelection.

findItem <faceselection> (<faceselection[<integer>] | <integer>)

Returns the selection index of the matching item or 0 if not found. The item is selection index or singleton FaceSelection.

Examples

-- move faces in 'mouth' named selection set

move $foo.faces[#mouth] [0,0,10]

-- select faces in 'front faces' set

select $baz.faces["front faces"]

-- set 'baz' named selection set to given faces

$foo.faces[#baz] = #(1,3,4,5,10)

-- set 'cursel' set to current selection

$baz.faces[#cursel] = $baz.selectedFaces

-- all the names of the face-level named selection sets for object $foo

$foo.faces.selSetNames

-- print out all face-level named selection sets

for n in $.faces.selSetNames do print $.faces[n]


EdgeSelection Values

An EdgeSelection represents a set of edges for a scene mesh node as a virtual array. As such, you can access an edge by index, iterate over the edges, and apply mapped functions to the edges. See also Editable_Mesh. The EdgeSelection array is dynamic, i.e., its contents will change as the edges or selected edges of the mesh node change. EdgeSelection values are mappable.

Constructors

<mesh>.selectedEdges -- the currently selected edges of the mesh object

<mesh>.Edges -- all of the edges of the mesh object, read-only

Properties

<edgeselection>.count : Integer, read-only

Returns the number of edges in the edge array.

<edgeselection>.selSetNames : Array of names, read-only

Returns an array of names of the current edge-level named selection sets for the object the EdgeSelection is associated with.

The following property is present for singleton selections (of the form $foo.edges[n]):

<edgeselection>.index : Integer, read-only

Returns the index of the selected element in the mesh, e.g.,

$foo.selectedEdges[2].index

returns the edge index of the 2nd edge in the current selection.

Note that iterating over a selection yields singleton selections in the loop body:

se = for i in $foo.selectedVerts collect i.index

se contains selected edges as array

Operators

<mesh>.selectedEdges = (<array> | <bitarray>)

Selects the specified edges.

<edgeselection>[<integer>]

Retrieves the indexed edge as a singleton EdgeSelection. Index starts at 1

<edgeselection>[(<integer_array> | <bitarray>)]

Retrieves the indexed edges as a EdgeSelection. Index starts at 1.

<edgeselection>[(<#name> | <string>)]

Retrieves the edge-level named selection set, where the name of the named selection set can be specified as a name or string value.

<edgeselection>[(<#name> | <string>)] = (<faceselection> | <integer_array> | <bitarray>)

Sets the edge-level named selection set to the specified edges. The name of the named selection set can be specified as a name or string value, and the edges can be specified as an array, bitArray, or a EdgeSelection from the same object.

Methods

move <edgeselection> <point3>

Moves the edges in the EdgeSelection.

select <edgeselection>

Selects the edges in the EdgeSelection.

deselect <edgeselection>

Deselects the edges in the EdgeSelection.

delete <edgeselection>

Deletes the edges in the EdgeSelection.

append <edgeselection> (<edgeselection> | <integer>)

Appends the edge(s) to the EdgeSelection.

findItem <edgeselection> (<edgeselection[<integer>] | <integer>)

Returns the selection index of the matching item or 0 if not found. The item is selection index or singleton EdgeSelection.

Examples

-- move edges in 'mouth' named selection set

move $foo.edges[#mouth] [0,0,10]

-- select edges in 'front edges' set

select $baz.edges["front edges"]

-- set 'baz' named selection set to given edges

$foo.edges[#baz] = #(1,3,4,5,10)

-- set 'cursel' set to current selection

$baz.edges[#cursel] = $baz.selectedEdges

-- all the names of the edge-level named selection sets for object $foo

$foo.edges.selSetNames

-- print out all edge-level named selection sets

for n in $.edges.selSetNames do print $.edges[n]


BitArray Values

The MAXScript BitArray class provides direct access to 3ds max's SDK BitArray class. The SDK BitArray is used throughout 3ds max to compactly encode selections as a string of bits.

Literals

#{ <selection> } -- these are curly-brackets

where <selection> is a comma-separated list of the following

<integer> -- integers must be > 0

<integer> .. <integer>

For example, #{1, 5, 10..200, 302} says that the bits 1, 5, 10 to 200, and 302 are "turned on". When used in connection with selections in 3ds max (such as vertex or face or control vertex) the "on" bits imply the elements or sub-objects with those indexes are selected.

Properties

<bitarray>.count : Integer, read-only

Returns the largest possible index held in the BitArray at that point in time. This value is independent of whether any particular indexes are selected or not. BitArrays grow dynamically as needed to accommodate the indexes used on it, just as with arrays.

Operators

<bitarray>[<integer>] -- yields true if selected, else false

<bitarray>[<integer>] = <boolean> -- sets or clears indexed bit

<bitarray> + <bitarray> -- union ("OR" operation)

<bitarray> - <bitarray> -- difference

-<bitarray> -- invert the bitarray

Methods

append <bitarray> <integer>

Adds index to bitarray, growing bitarray if necessary.

join <bitarray> <bitarray>

Union ("OR" operation) of the two bitarrays.

findItem <bitarray> <integer>

Yields index <integer> if selected, 0 otherwise.

deleteItem <bitarray> <integer>

Clears the index selection.

copy <bitarray>

Creates an independent copy of the bitarray.

Notes

BitArrays can be used interchangeable with ordinary #(...) arrays 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

A MAXKeyArray represents all the keyframe keys in a 3ds max controller track. See also MAXKey Values, Working with MAXKey Values, and Controller Common Properties, Operators, and Methods. MAXKeyArray values are mappable.

Constructors

<node>.<animatable_property>.keys

The key array can be accessed using the keys property on an animated 3ds max object property. Examples:

$foo.position.keys

$foo.twist.angle.keys

If the 3ds max object parameter is not yet animated (i.e., no controller has been assigned to the parameter), a value of undefined is returned.

<controller>.keys

The key array can be accessed using the keys property on a controller. Examples:

$foo.position.controller.keys

$foo[3][1].keys

Properties

<key_array>.count : Integer, read-only

Returns the number of keys in the key array.

Operators

<key_array>[<index_integer>]

Returns a MAXKey value representing the indexed key in the key array. Indexes start at 1.

Methods

append <key_array> <key>

Appends key to key array.

deleteItem <key_array> <index_integer>

Deletes the indexed key. Key indexes are 1-based.

addNewKey <key_array> <time> [ #select ]

Adds a new key to the key array at the time specified. The value for the new key is the interpolated controller value at the specified time. The new key is also selected if the #select optional argument is specified. The value for the new key is the interpolated controller value at that time. addNewKey() will not add a key if a key already exists at the specified time. The return value in this case is the key located at the specified time.

deleteKeys <key_array> [ #allKeys ] [ #selection ]

Deletes keys from the controller according to the optional symbolic argument supplied.

#allKeys (default): deletes all keys in the controller.

#selection: deletes the currently selected keys

deleteKey <key_array> <index_integer>

Deletes the indexed key. Key indexes are 1-based.

moveKeys <key_array> <time> [ #selection ]

Moves all keys by the time given. If #selection is specified, move the current selection otherwise move all keys.

sortKeys <key_array>

Re-sorts keys according to their times. Some MAXKey operations can result in out of order keys and this function must be called to correctly order keys.

Note: 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. 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. ModifierArray values are mappable.

Constructors

<node>.modifiers

Properties

<modifierarray>.count : Integer, read-only

Returns the number of modifiers in the modifier array.

Operators

<modifierarray>[<integer>]

Retrieves indexed modifier. Index is 1-based with 1 being the modifier on the top of the modifier stack.

<modifierarray>[( <name> | <string> )]

Retrieves named modifier using modifier name as string or name.


MaterialLibrary Values

A MaterialLibrary contains a table of materials as an array. The 3ds max system global variables currentMaterialLibrary and sceneMaterials contain MaterialLibrary instances. System global variable meditMaterials strictly speaking is not a MaterialLibrary value, rather it is a virtual array of the materials in the Material Editor sample slots. In most cases, meditMaterials can be considered a MaterialLibrary value, with the exception that you can assign a material or textureMap value to a meditMaterials element. MaterialLibrary values are mappable.

Constructors

currentMaterialLibrary -- system global

sceneMaterials -- system global, the materials in the scene

meditMaterials -- system global, the materials in material editor

materialLibrary { <material> }

Creates a temporary material library. You can add materials to this library with the append function, but there is currently no way to save it or make it the current library.

Properties

<mat_lib>.count : Integer, read-only

Returns the number of materials in the library.

Operators

<mat_lib>[ <integer> | <name> | <string> ]

Retrieves a material from the material library. Material libraries can be indexed just like arrays with an integer index, or by using the material name as a Name or String value.

<mat_lib>[ <integer> | <name> | <string> ] = ( <material> | <textureMap> )

Assigns the specified material or textureMap to the material library. Material libraries can be indexed just like arrays with an integer index, or by using the material name as a Name or String value. If the material library is indexed by an index value, and the index value is larger than the size of the material library, a runtime error is generated. If the material library is indexed by a material name, and the material name is not already present in the material library, the material or textureMap is appended to the material library.

meditMaterials[<slot_index_integer>]

Returns the material or textureMap in the indexed material editor slot. Valid <slot_index_integer> values are 1 through 24.

meditMaterials[<slot_index_integer>] = ( <material> | <textureMap> )

Assigns the specified material or textureMap to the indexed material editor slot. Valid <slot_index_integer> values are 1 through 24. For example:

meditMaterials[3]= standard()

Methods

append <mat_lib> <material>

Append the specified material to the material library. This method is not applicable to the meditMaterials material library.

deleteItem <mat_lib> ( <integer> | <name> | <string> )

Delete the specified material from the material library. The material can be specified as the indexed material in the material library, as a String, or as a Name. This method is not applicable to the meditMaterials material library.

findItem <mat_lib> <material>

Returns the index of the material in the material library or zero if the material is not in the material library.

Associated Methods

getMeditMaterial <slot_index_integer>

Returns the top level material or textureMap in the specified material editor slot. Valid <slot_index_integer> values are 1 through 24. For example:

foo = getMeditMaterial 3

setMeditMaterial <slot_index> ( <material> | <textureMap> )

Complements the getMeditMaterial function allowing you to place a material or textureMap into the numbered material editor slot.

loadDefaultMatLib()

Loads the default 3ds max material library file.

loadMaterialLibrary <filename_string>

Loads the named 3ds max material library file, which becomes the current material library. If the file name does not have a fully specified directory path, the function searches through all the currently configured bitmap paths. Returns true if the loads succeeds, false if it fails.

saveMaterialLibrary <filename_string>

Saves the current material library into the named file. Returns true if the save succeeds, false if it fails.

fileOpenMatLib()

This method displays the File Open dialog and allows the user to select a material library to load. Note: If the Material/Map Browser is open when fileOpenMatLib() is called, the Material/Map Browser display is not updated.

fileSaveAsMatLib()

Displays the standard Save File As dialog to allow the user to save the current material library.

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. NURBSSet values are mappable.


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

Dynamic Properties

Indexed Access to Animatable Properties

Third-Party Plug-In Classes


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 are accessible.

apropos

The apropos() function is used to search for and print out information about global variables by name pattern and class of contents. This function has the form:

apropos <pattern_string> [ to:<stream> ]

The <pattern_string> argument is a string containing a wild-card pattern for matching against global variables. The pattern form is:

<variable_name_pattern_string[:class_name_pattern_string]>

that is, a global variable name pattern optionally followed by a ':' and a class name pattern. If the optional class name pattern is given, it restricts the printout to globals containing values of the specified classes. The apropos() function assumes a wild-card '*' at the start and end of each pattern, implying a 'contains' pattern match. The pattern strings can contain name characters and '*'s and '?'s.

The output consists of the global variable name, a tag in () indicating if the variable is a system or const (unchangeable) variable and the class of the value currently in it, followed by a printed representation of that value.

Examples:

apropos "light" -- any variables with 'light' in the variable name

apropos ":float" -- any variables containing float values

apropos "" to:f -- dump all variables to the stream f

apropos "controller:super" -- the list of controller superclasses

apropos "foo:control" -- any variables whose name contains 'foo'

-- and that contain controller classes

Here's a fragment of the first example's output:

lights (const ObjectSet): $lights

lightLevel (system Float): 1.0

Sunlight (const MAXClass): Sunlight

Directionallight (const MAXClass): Directionallight

lightLevelController (system Control): Controller:Bezier_Float

light (const MAXSuperClass): light

NewLight (const Primitive): NewLight()

lightTintColor (system Color): (color 255 255 255)

Volume_Light (const MAXClass): Volume_Light

lightTintColorController (system Control): Controller:Bezier_Color

gw.getMaxLights (Primitive): getMaxLights()

gw.setLight (Primitive): setLight()

showClass

The showClass() function prints information about a specified 3ds max class or classes. It has the following form:

showClass <pattern_string> [ to:<stream> ]

where <pattern_string> is a string containing a wild-card pattern to match against 3ds max class names, superclass names and property names, and the optional to:<stream> keyword argument specifies a Stream Value to output the display to. The pattern string has this form:

"<class_name>[ :<superclass_name> ][ .<property_name> ]"

Examples:

showClass "path*" -- all 3ds max classes starting 'path'

showClass "noise.*" -- all the accessible properties on the

-- Noise texture map

showClass "*:mod*" -- all the modifier classes

showClass "*.*rad*" -- all the classes with a property name

-- containing 'rad'

showClass "*.*" to:f -- everything, out to a file

showClass "*:*controller*" -- all the classes that have

-- "controller" in their superclass

-- name

In the output from the last example, the controllers include 3ds max's core controllers and any 3rd-party plug-in controllers. In some cases, embedded controllers for some complex plug-ins may be visible in the showClass() listing (such as for Character Studio and HyperMatter). You should not attempt to create and use these controllers individually, this may result in system exceptions.

If you leave out the superclass pattern (the ':' part), it matches all superclasses. If you leave out the property pattern (the '.' part), you only get class names printed.

Note

This function only displays matching MAXWrapper classes (nodes, modifiers, materials, etc.), not the foundation classes in MAXScript (float, integer, array, point3, etc.).

The following shows examples of the output of showClass():

Script:

showclass "box*" -- show all classes whose name starts with "box"

showclass "box.*" -- show all properties for class box

Output:

Box : GeometryClass {10,0} -- start of output from line 1

BoxGizmo : helper {3bc31904,67d74ec9}

OK -- result returned from line 1

Box : GeometryClass {10,0} -- start of output from line 2

.height : float

.length : float

.lengthsegs : integer

.width : float

.widthsegs : integer

.mapCoords : boolean

.heightsegs : integer

OK -- result returned from line 2

showProperties

The showProperties() function is used to display the properties for a specific object that is an instance of one of the MAXWrapper classes. It can be used in place of showClass() in situations where you have an actual object in hand. Unlike showClass(), it can display the dynamic properties that may appear in individual objects as you work on them in the scene, such as the sub-controllers in a list controller or the animated control points in an FFD modifier.

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 to output the display to.

If the property name pattern is not supplied, all properties are listed.

Examples:

showProperties $foo.bend -- show properties of the bend modifier on object foo

ffdmod = $baz.'FFD_box__4x4x4' -- point to the FFD modifier on object baz

showProperties ffdmod "disp*" to:log -- show properties starting with "disp" in the

-- FFD modifier

showProperties $foo.pos.controller -- sub controllers in a position list controller

Note: When the 3ds max entity specified is a node (for example $box01), this function only displays the properties of base object. It does not show the properties of the transform controllers, modifiers, or materials applied to the object. To display the properties for one of these objects, that object must be specified as the 3ds max entity as shown in the above examples.

The following shows examples of the output of showProperties:

Script:

b=box() -- create a box

ffd_mod=ffdBox() -- create a ffdBox modifier

addmodifier b ffd_mod -- apply ffdBox modifier to the box

showproperties b -- show all properties for the box

showproperties ffd_mod -- show all properties for the ffdBox modifier

Output:

$Box:Box07 @ [0.0000,0.0000,0.0000] -- result from line 1

FFD_box__4x4x4:FFD(box) 4x4x4 -- result from line 2

OK -- result from line 3

.height : float -- start of output from line 4

.length : float

.lengthsegs : integer

.width : float

.widthsegs : integer

.mapCoords : boolean

.heightsegs : integer

OK -- result from line 4

.dispLattice (Lattice) : boolean -- start of output from line 5

.dispSource (Source Volume) : boolean

.deformType (<unknown>) : integer

.falloff : float

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

As a special case, you can also call getPropNames() on the superclass 'Node' to get the list of properties common to all scene nodes such as .position, .name, or .wireColor. For example:

getPropNames node

getProperty and setProperty

The getProperty() and setProperty() functions allow you to access and set properties using computed property names: These form for each of these functions are:

getProperty <obj> <property_name>

setProperty <obj> <property_name> <value>

The property name can be either a name, for example #length, or a string, for example "length", so you can construct property names with string operations.

Examples:

getProperty foo #x -- equiv. to foo.x

setProperty $foo "radius" 23 -- equiv. to $foo.radius = 23

getProperty $foo.ffd_2x2x2 ("control_point_" + n as string)

The getPropNames() function can be used in conjunction with the getProperty() function to implement object 'dumping' tools that can iterate over all the properties of an arbitrary object and output them as required. For example,

for p in getPropNames $foo do

format "% = %\n" p (getProperty $foo p)

Similar functions for accessing and setting the values of property-assigned controllers are:

getPropertyController <value> <string_or_name>

setPropertyController <value> <string_or_name> <controller>

Get and set the controller assigned to the named property of the value. If no controller has been assigned to the property, a value of undefined is returned.

SubAnims and ParamBlocks

3ds max stores all of properties for objects in structures called subAnims. In some cases, a subAnim will contain nested subAnims. An example of this can be seen with the Standard material. If you apply a Standard material to an 3ds max object, and then expand the object's tracks in Track View to display the material, you will see three Track View nodes - Parameters, Maps, and Shader. Each of these nodes is a subAnim defined in the Standard material's class. Expanding the tracks for these three nodes, you will see various properties listed. These properties are defined in each of the nested subAnims in a structure called a ParamBlock.

MAXScript automatically finds animatable properties in all ParamBlocks associated with an object. To access these properties, you use the same nesting as shown in Track View when referencing those properties in MAXScript. For example, you would access the Ambient Color property in a Standard material in MAXScript as:

$box01.material.shader.diffuse_color

For more information about accessing animatable properties in MAXScript, see also Indexed Access to Animatable Properties in 3ds max Objects.

The properties accessible on the various kinds of values is documented for each class. Many of the foundation classes in MAXScript (such as point3, color, etc.) support a special kind of nested-property assignment which allows sub-properties on object properties, such as the .x, .y, and .z coordinates in a node's .position property, to be individually and directly set. See Nested Object Properties 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 Class and Object Inspector Functions.


Indexed Access to Animatable Properties in 3ds max Objects

As an alternative to using named property accesses, you can access in an object any animatable property that is visible as a track in Track View by indexing the 3ds max object value as though it were an array. This simplifies such tasks as iterating over all the animatable properties in an object and accessing sub-controllers that don't have unique names, such as within list controllers.

Properties

<maxwrapper_object>.numSubs : Integer, read-only

Yields the number of accessible sub-animatables, or tracks, in an object. This is the number of immediate children subAnims, and may include as yet invisible tracks in the track view, such as visibility tracks on a node or yet-to-be animated vertices in an FFD. This property operates on any MAXWrapper subclass.

Methods

getSubAnimName <maxwrapper_object> <index>

getSubAnimNames <maxwrapper_object>

Provides access to the Track View names of subAnims. The getSubAnimName() function takes a subAnim index and returns a Name instance. The getSubAnimNames() function returns an array of names in subAnim index order.

getSubAnim <maxwrapper_object> <index>

Returns the indexed subAnim. See the index operator below.

Operators

<maxwrapper_object>[<index_number>]

Returns the indexed subAnim. You can apply the index operator, [<index_number>], to any MAXWrapper object (nodes, modifiers, controllers, materials, etc.) to access a numbered subAnim. For example:

for i in 1 to $foo.numSubs do print $foo[i] -- iterate them

$bar.position.controller[3] -- third subAnim in a position list controller

ffd_mod[i].value -- position of i'th FFD control point

You cannot set subAnims with the index operator, this is a read-only access.

-- SubAnim Class

MAXScript defines a SubAnim class, instances of which provide a general representation for sub-animatables. Whenever you use the index operator on a 3ds max object, it returns a SubAnim instance. For example:

$box01[3] -> SubAnim:Transform

The third subAnim in a node is typically the transform track.

Properties

<subAnim>.value : Value

The current value of the track subAnim, equivalent to <controller>.value. Returns undefined if no appropriate value exists or the track has not yet been assigned a controller. The .value property yields the value at the current MAXScript time. You can assign to this value to set the track's value at that time.

<subAnim>.controller : Controller

The controller for the track SubAnim. Returns undefined if a controller has not yet been assigned or if the SubAnim is not animatable. You can assign a new controller to a track by assigning to the .controller property of its subAnim.

<subAnim>.keys : KeyArray, read-only

Yields the key array for that track or undefined if not keyable or a controller has not yet been assigned. This property is read-only.

<subAnim>.isAnimated : Boolean, read-only

Yields true if there is an animated controller present. This property is read-only.

<subAnim>.object : MAXWrapper, read-only

Yields the subAnim object, or undefined if not assigned. This property is read-only. The .object property may return any kind of MAXWrapper object, depending on what the parent object decides to put there. For example, <node>[1].object is the visibility controller or undefined if not yet assigned, <node>[2].object contains the bindings of any space warps bound to the node, or undefined if none have been bound, <node>[3].object is the transform controller, <node>[4].object is the node's object, either the modified object if there are modifiers present or the base object if not, <node>[5].object is the material assigned to the node or undefined if no material has been assigned, and <node>[6].object is the Image Motion Blur Multiplier controller or undefined if not yet assigned,. For example:

b = box()

b[4].object -- returns a reference to the Box base object

<subAnim>.numSubs : Integer, read-only

The number of immediate subAnim children.

If you attempt to access subAnim properties, such as .value, .numSubs, .category, etc., on certain subAnims that had yet to be assigned controllers, such as scene node visibility tracks, these properties return null values such as 0, or undefined, as appropriate.

Methods

getSubAnim <subAnim> <index>

Returns the indexed subAnim. See the index operator below.

Operators

<subAnim>[<index_number>]

Returns the indexed subAnim. You can work down through nested subAnims (nested tracks) by indexing into subAnims themselves. For example,

$box01[3][2]

yields the rotation track subAnim since <node>[3] is always the transform track and the second track in it is always the rotation track. Indexing a SubAnim always yields another SubAnim. For those familiar with SubAnims in the 3ds max SDK, it should be noted that 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 classes are the core 3ds max classes that are supported directly within MAXScript. Many of the kinds of 3ds max objects you will work with are provided through 3rd-party plug-ins for 3ds max, they are not built directly in to MAXScript.

For these classes, an automatic plug-in detector scans for plug-ins that MAXScript doesn't internally know about and attempts to provide MAXScript access to them. This includes new core classes in new releases of 3ds max that MAXScript doesn't internally know about, and 3rd-party plug-ins (such as HyperMatter, Sand Blaster, Surface Tools, etc.). Not all parameters and properties of the detected plug-ins are accessible. In general, the detector will only find animatable parameters on these plug-ins, and in some cases none at all, if the plug-in uses non-standard parameter coding.

You can use the class and object inspector functions 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 MAXWrapper Common Properties, Operators, and Methods.

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.

See also

Node

Modifier and SpacewarpModifier

Material

Atmospheric

Controllers

Render Effect


MAXWrapper Common Properties, Operators, and Methods

The following properties and methods are applicable to any value that is derived from MAXWrapper.

Properties

The following MAXWrapper value and class properties give you access to the plug-in category, such as Standard Primitives, Extended Primitives, or Particle Systems:

<MAXWrapperobject>.category Name, read-only

<maxclass>.category Name, read-only

<maxsuperclass>.categories Array, read-only

The category property returns a Name value containing the category. You can use it on either a 3ds max object class, such as Line, Box, or Fog, or on an instance of any 3ds max object class. For scene nodes, the category usually corresponds to one of the names in the drop down list in the Create panel. These are the categories such as #Standard_Primitives, #Compound_Objects, and #Particles_Only.

For modifiers, the category determines which group the modifier appears in the Configure Button Sets / Modifiers list. These are the categories such as #MAX_STANDARD, #MAX_EDIT, and #MAX_SURFACE.

For textures, the category determines which group the texture appears in the Material/Map Browser. These are the categories such as #2D (2D maps), #3D (3D maps), and #COMP (Compositors).

The categories property can be used on any of the 3ds max object superclasses, such as Shape, GeometryClass, Helper, SpacewarpObject, TextureMap, or Modifier, to get a list of the available categories for that superclass, returned as an array of Names. For example:

$line01.category -- returns #Splines

Gengon.category -- returns #Extended_Primitives

Shape.categories -- returns #(#Shape, #Splines, #NURBS_Curves)

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

exprForMAXObject <MAXWrapper_object>

Returns a string containing a MAXScript expression that will 'name' the specified MAXWrapper object using property access and indexes as needed. For example, if you have in variable m a bend modifier on a scene object named "foo", then:

exprForMAXObject m

would yield the string:

"$foo.bend"

This method is an exposure of an internal method that macro recorder uses, and its output will vary depending on the macro recorder options.

b=box()
--> $Box:Box02 @ [0.000000,0.000000,0.000000]
c=b.pos.controller
--> Controller:Bezier_Position
exprformaxobject c
--> "$Box02.pos.controller"
bm=bend()
--> Bend:Bend
addmodifier b bm
--> OK
exprformaxobject bm
--> "$Box02.modifiers[#Bend]"

Here, changing the macro recorder options from "Explicit scene object names" to "Selection-relative scene object names", yeilds:

exprformaxobject bm
--> "$.modifiers[#Bend]"

createInstance <maxclass> [keyarg1:v] [keyarg2:v] ...

This method is used to directly create the 'base objects' that you see in a Node (or any other object). The main use for this is to create temporary geometry base objects from which meshes will be extracted to help create the meshes for scripted geometry primitive plug-ins. The optional <keyargs> are the same base-object keyword arguments as can be supplied for the class constructor. These are typically the parameters of the base object. For example:

b = createInstance Box length:10 height:40 width:20

creates an instance of a Box. This box will not appear in the 3ds max viewports, as it is not a node. It only contains the geometry associated with the Box object. You can get at the mesh representation of these instanced objects with the mesh property, which yields a TriMesh value.

replaceInstances <old_MAXWrapper> <new_MAXWrapper>

Replaces all instances of the old MAXWrapper with the new MAXWrapper. Old and new MAXWrapper must have the same superclass.

Minimal error checking, use with extreme caution.

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.

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

See also

Access to MAXWrapper AppData

Nested Object Controller Functions

Nested Object Properties

Note Track Access


Access to MAXWrapper AppData

The AppData access methods give a simple form of access to the AppData capability in the 3ds max SDK. The AppData mechanism provides a way for plug-ins to attach arbitrary data to any 3ds max object in a scene, such as nodes, materials, modifiers, controllers, etc., that is permanently stored with that object in the 3ds max scene file.

The following methods are used to read and store AppData for a MAXWrapper object:

setAppData <MAXWrapper_object> <integer_ID> <string>

Sets the AppData item of the given ID number on the given 3ds max object to the <string> value. This creates a new item if needed or replaces the string contents if an item of that ID already exists.

getAppData <MAXWrapper_object> <integer_ID>

Returns the AppData item string of the given ID number from the given 3ds max object. Returns the value undefined if the ID'd item is not present.

deleteAppData <MAXWrapper_object> <integer_ID>

Deletes the AppData item if the given ID number from the given 3ds max object.

clearAllAppData <MAXWrapper_object>

Clears out all MAXScript-related AppData items from the given MAXWrapper object.

You can add as many AppData strings as you like to an object—you assign them each an integer identification number when they are first added and access them later using those IDs.

AppData strings can be attached to any MAXWrapper subclass instance, including scene nodes, modifiers, controllers, materials, atmospherics, etc. Note that the AppData is stored in the scene file only if its object is in the scene—if, for example, you create a material in MAXScript and do not assign it to any object or the material editor, it will not be saved in the scene file nor will its AppData.

If you want to associate certain AppData strings with the scene as a whole, it is recommended that you create a hidden dummy node with a unique name and attach the scene AppData to that node.

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. 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 and Controller Time Functions.

Examples:

insertTime $box01.xform 0f 10f

-- all keys after 0f in all controllers in the XForm modifier are moved by 10f

insertTime $box01 0f 10f

-- all keys after 0f in box01 are moved (transform, creation, modifiers)

selectKeys $box02.xform.gizmo.rotation.controller 0f 100f

-- selects keys in 0-100f. If controller is Euler, will select x, y and z keys

deleteTime $box* 10f 10f

-- delete 10f at frame 10 in all keys in all objects named $box* (works with—any pathname or array of objects)

insertTime $box03.children 0f 10f

-- inserts time in all controllers of all children of $box03

reduceKeys $box01.modifiers

-- applies key reductions to all controllers in all modifiers in $box01 (leaves—transform and creation parameters alone)


Nested Object Properties

Several of the properties on 3ds max objects contain values that are themselves compound, for example <node>.pos yields a Point3, which itself contains x, y and z properties. MAXScript provides a mechanism that lets you modify these nested properties on MAXWrapper objects in place such that assignment to them will affect that nested property on the 3ds max object. This mechanism depends on the nested property being accessed in one, cascaded property access. For example:

$foo.pos.x += 23 -- move the node 23 units in x

$baz.rotation.angle *= 2 -- double the rotation

If you first get the intermediate value into some variable and then set the property on that value, the change will not be reflected in the original object, the connection is only maintained within a single cascaded property access. For example:

p = $foo.pos -- get foo's position as a 'detached' point3

p.x += 23 -- set the x prop of that point, it doesn't know

-- about foo anymore, foo's pos is not changed

In this case, you would have to explicitly re-assign the free-standing point to $foo's position to affect $foo:

$foo.pos = p -- set foo's new position

In general, any property on a MAXWrapper object that is itself a foundation compound value such as a Point3 or Quat will yield a free-standing value when simply accessed and supports object sub-property assignment in cascaded property assignment.


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

MAXNoteKeyArray Values

MAXNoteKey Values

Working with Note Tracks


Notetrack Values

The following methods are related to creating, adding, deleting Note tracks. See MAXNoteKeyArray Values and MAXNoteKey Values for information on accessing the contents of Note tracks.

Constructor

notetrack <name_string>

Creates a new, empty note track with the specified name. The name is only used to differentiate different note tracks in MAXScript but is not visible in 3ds max.

Properties

<noteTrack>.keys MAXNoteKeyArray

<noteTrack>.name String

Methods

getNoteKeyTime <notetrack> <index>

Returns the time of indexed note key.

getNoteKeyIndex < notetrack > <time>

Returns the index of the note key at the specified time.

Associated Methods

addNoteTrack <MAXWrapper_object> <NoteTrack>

Adds a new note track to the MAXWrapper object.

deleteNoteTrack <MAXWrapper_object> <NoteTrack>

Deletes specified note track from the MAXWrapper object.

hasNoteTracks <MAXWrapper_object>

Deletes specified note track from the MAXWrapper object.

numNoteTracks <MAXWrapper_object>

Returns the number of note tracks applied to the MAXWrapper object as an integer.

getNoteTrack <MAXWrapper_object> <index_integer>

Returns the indexed note track applied to the MAXWrapper object. Index is 1-based.


MAXNoteKeyArray Values

A MAXNoteKeyArray represents all the note keys in a 3ds max note track. See also MAXNoteKey Values and Notetrack Values. MAXNoteKeyArray values are mappable.

Constructors

<NoteTrack>.keys

The note key array can be constructed by accessing the keys property on the note track. Example:

nt=getNoteTrack $foo.position.controller 1 -- get first note track on controller

ntk=nt.keys -- note key array for note track

Properties

<NoteKeyArray>.count : Integer, read-only

returns the number of objects in set

Operators

<NoteKeyArray>[<index_integer>] -- accesses member of collection. Indexes start at 1.

Methods

addNewNoteKey <NoteKeyArray> <time>

Adds a new note key to the note key array at the time specified. The value for the new note key is a null string. Returns the note key added.

deleteNoteKeys <NoteKeyArray> ( #allKeys | #selection )

Deletes note keys from the note key array according to the optional symbolic argument supplied.

#allKeys: deletes all keys in the note key array.

#selection: deletes the currently selected note keys

deleteNoteKey <NoteKeyArray> <index_integer>

Deletes the indexed note key. Key indexes are 1-based.

sortNoteKeys <NoteKeyArray>

Re-sorts note keys according to their times. Some MAXNoteKey operations can result in out of order note keys and this function must be called to correctly order note keys.

Associated Methods

getNoteKeyTime <notetrack> <index>

Returns the time of indexed note key.

getKeyIndex < notetrack > <time>

Returns the index of the note key at the specified time.


MAXNoteKey Values

Note tracks store their notes as MAXNoteKeys. As seen by MAXScript, note keys are stored in a MAXNoteKeyArray. The MAXNoteKeyArray for a note track is accessed via the keys property of the note track.

For more information on MAXNoteKeyArrays, see MAXNoteKey Values.

Constructor

addNewNoteKey <MAXNoteKeyArray> <time> [ #select ]

Adds a new note key to the note track at the time specified. The new note key is also selected in the track view if the #select optional argument is specified. The value for the new note key is a null string.

<MAXNoteKeyArray>[<index_integer>]

Properties

<MAXNoteKey>.time Time -- time value or number (interpreted as frames)

<MAXNoteKey>.selected Boolean -- specifies whether the key is selected. Read/write access.

<MAXNoteKey>.value String -- string contained in the note key


Working with Note Tracks

Changing the time property of a note key may cause it to go out of time order relative to the other keys in the controller. You must call the sortKeys() function on the controller or associated MAXNoteKeyArray once all key time manipulations of this kind is complete so that animation will perform correctly.

Example

Script

s = sphere() -- create a sphere

--

ntp1 = NoteTrack "PosNT1" -- create a note track

ntp2 = NoteTrack "PosNT2" -- create another note track

addNoteTrack s.pos.controller ntp1 -- apply first note track to sphere's pos controller

addNoteTrack s.pos.controller ntp2 -- apply second note track to sphere's pos controller

numNoteTracks s.pos.controller -- check number of note tracks on pos controller

hasNoteTracks s.pos.controller -- test to see if pos controller has note tracks

--

addNewNoteKey ntp1.keys 20 #select -- add key to first note track, and select the key

addNewNoteKey ntp1.keys 40 -- add another key to first note track

--

n = getNoteTrack s.pos.controller 1 -- retrieve first note track on the pos controller

nk=n.keys -- retrieve an instance of the note track key array

--

nk[2].value = "Yo What's Up" -- set value for second note key

nk[2].time = 10 -- change the time for second note key. Now first key

nk[1].selected = true -- select the first note key

sortNoteKeys nk -- changed the time of the note keys, so re-sort

nk.count -- check number of keys

nk -- display the note keys

--

-- To delete the note tracks and note keys

deleteNoteKey nk 1 -- delete first note key

deleteNoteKeys n.keys #allKeys -- delete all the note keys

deleteNoteTrack s.pos.controller ntp1 -- remove note track from pos controller

deleteNoteTrack s.pos.controller ntp2 -- remove note track from pos controller

Output

$Sphere:Sphere02 @ [0.0,0.0,0.0] -- result line 1

Notetrack:PosNT1 -- result line 3

Notetrack:PosNT2 -- result line 4

OK -- result line 5

OK -- result line 6

2 -- result line 7

true -- result line 8

#Note key(1 @ 20f) -- result line 10

#Note key(2 @ 40f) -- result line 11

Notetrack: -- result line 13

#keys(20f, 40f) -- result line 14

"Yo What's Up" -- result line 16

10 -- result line 17

true -- result line 18

OK -- result line 19

2 -- result line 20

#keys(10f, 20f) -- result line 21

OK -- result line 24

OK -- result line 25

OK -- result line 26

OK -- result line 27


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 Node Subclasses. 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 Node Common Properties, Operators, and Methods.

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 MAXWrapper Common Properties, Operators, and Methods.


Node Common Properties, Operators, and Methods

The following properties and methods are applicable to any value that is derived from Node.

Constructors

<non_wild_card_pathname>

identifies a unique node in the scene

<objectset>[<integer>]

<wild_card_pathname>[<integer>]

n'th scene object in collection

<node_constructor> [ name: <string> ] \

[ prefix: <string> ] \

[ material: <material> ] \

[ target: <node> ] \

[ pos: <point3> ] \ -- default [0,0,0]

[ position: <point3> ] \ -- synonym for pos

[ rotation: <quat> ] \ -- default 0 rotation

[ scale: <point3> ] \ -- default 100% scale

[ pivot: <point3> ] \ -- default normal node pivot location

[ transform: <matrix3> ] \ -- default identity

[ isSelected: <boolean> ] \ -- default false

[ dir: <point3> ] -- set local z direction

The position and rotation values are relative to the current active grid if 'coordsys grid' is the current working coordinate system.

A <node_constructor> is one of the scene node classes listed in Node Subclasses, such as box, sphere, quadPatch, splineShape, etc. For example:

b = box name:"foo" position:[10,10,10] height:20

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 General Node Properties and Node Transform Properties for details about the properties accessible on scene nodes.

Methods

Most node methods are automatically mapped over node collections.

IsValidNode <var>

Returns true if <var> is a node value, and the node has not been deleted. Otherwise, it returns false.

move <node> <point3> -- mapped

scale <node> <point3> -- mapped

rotate <node> <angle> <axis_point3> -- mapped -- angle in degrees

rotate <node> <quat> -- mapped

rotate <node> <eulerangles> -- mapped

all the transform operations operate in the current working coordinate system. See Context Expressions.

copy <node> -- mapped

reference <node> -- mapped

instance <node> -- mapped

All the clone operations can take any of the standard node creation optional keyword arguments which are applied after the node has been copied.

These functions clone all the original node's transform controllers and keys and the visibility controller and its keys if a visibility track has been assigned.

snapshot <node> -- mapped

This function provides functionality similar to the SnapShot tool in 3ds max. It generates a new node that contains a copy of the world-state mesh of the source <node> at the time that the snapshot is made. Any existing modifiers are collapsed out of the new node and the mesh snapshot accounts for any space warps currently applied. As with the clone methods (copy, reference and instance,) you can add any of the standard node creation keyword arguments, such as pos:, name:, etc. The following example achieves an animation-based snapshot similar to the SnapShot tool in 3ds max:

for t in 0 to 100 do at time t snapshot $foo

delete <node> -- mapped

Deletes the specified node(s).

instanceReplace <dest_node> <src_node> -- mapped

referenceReplace <dest_node> <src_node> -- mapped

Lets you turn existing nodes into instances and references to other nodes. You can use these, for example, to replace the geometry of one node with another, perhaps for implementing custom level-of-detail tools.

The <dest_node> is turned into an instance or reference to the <src_node>. As a new instance, existing geometry and modifiers are removed and replaced by the <src_node>'s, but all the node-related properties are kept, such as material, transform, visibility, name, etc. As a new reference, the base object for the <dest_node> becomes the world-state of the <src_node>, such that any changes to the src_node will affect the <dest_node>, but changes to the <dest_node> are local to it.

It is possible to develop a custom scripted version of the File/Replace function with these functions and the mergeMAXFile() function by temporarily changing the name of a node in the current scene, merging in that named node from another, making the first node an instance of the newly merged node with instanceReplace(), deleting the newly merged node and renaming the old node back again.

Both these functions are collection mapped, so you can make a selection of objects all instance or reference the same object, for example:

instanceReplace $foo* $baz

makes all the foo* objects be instances of baz's geometry and modifier stack.

attachObjects <node1> <node2> [ move:<boolean> ]

Makes <node2> a child of <node1>. Resets the current location of <node2> to the location of <node1> unless move:false is specified.

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 Modifier and SpacewarpModifier for more information about working with the modifier stack.

getPolygonCount <node>

Returns a 2 element array containing the current number of faces for the node in the first element, and the current number of vertices for the node in the second element. The number of faces and vertices returned are the number that would be present if the node was converted to a mesh object.

isShapeObject <node>

Returns true if the node is a shape object, false otherwise

numSurfaces <node>

Returns the number of parametric surfaces in the object. At the current time, Loft objects are the only objects where more than one surface is present (ie. loft of a donut).

isSurfaceUVClosed <node> <surface_index_integer>

Returns a 2 element array indicating if the parametric surface is closed in the U and V dimensions (ie. a torus is closed in both U and V). Note that not all objects have this method implemented, and will return a default value of #(true, true).

getTransformAxis <node> <index>

Returns the transform axis of the indexed axis system of the node as a <matrix3> value. Normally a node just has 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.

For example:

fn axisRotate obj rotation =

( local axis

local objA = if classof obj == objectSet or classof obj == array then obj else #(obj)

if getCoordCenter() != #local then

( axis = getTransformAxis objA[1] 0

for obj1 in objA do in coordsys axis about axis rotate obj1 rotation

)

else

( for obj1 in objA do

( axis = getTransformAxis obj1 0

in coordsys axis about axis rotate obj1 rotation

)

)

)

invalidateTM <node>

Invalidates the node's transformation matrix cache.

invalidateTreeTM <node>

Invalidates the node's transformation matrix cach and notify the node's subtree that the transformation matrix has changed.

The following MAXScript function can be used to force an update of an object whose transform is partially controlled by a scripted controller (such as a script controller on the position track):

mapped fn TMInvalidate obj =

( at time (currenttime-1) obj.transform

nodeInvalRect obj

invalidateTreeTM obj

redrawViews()

)

invalidateWS <node>

Invalidates the node's world space cache.

getNodeByName <string> exact:<boolean>

Returns first <node> with the specified name. String case is insensitive unless exact:true.

Default is exact:false

snapshotAsMesh <node>

Returns world state of node as a <mesh> value.

getInheritanceFlags <node>

setInheritanceFlags <node> (#all | #none | <bitarray>) keepPos:<boolean>

Get and set the inheritance flags for the specified node as an <bitarray>. If a bit is on, the corresponding inheritance is turned on. The order of the bits is: #{POS_X,POS_Y,POS_Z,ROT_X,ROT_Y,ROT_Z,SCALE_X,SCALE_Y,SCALE_Z}

If keepPos:false is specified, the node may move when an inheritance is turned on or off.

getTransformLockFlags <node>

setTransformLockFlags <node> (#all | #none | <bitarray>)

Get and set the transform lock flags for the specified node as an <bitarray>. If a bit is on, the corresponding transform lock is turned on. The order of the bits is: #{POS_X,POS_Y,POS_Z,ROT_X,ROT_Y,ROT_Z,SCALE_X,SCALE_Y,SCALE_Z}

Render-Related Methods

getInheritVisibility <node>

Returns true if the node inherits the visibility of its parent object (if any), false if not.

setInheritVisibility <node> <boolean>

Sets whether the node inherits the visibility of its parent object (if any). If <boolean> is true, node inherits visibility. If <boolean> is false the node does not inherit visibility.

getVisController <node>

Returns an instance of the node's visibility controller. Returns undefined if the node does not have a visibility track.

getImageBlurMultController <node>

Returns the node's Image Motion Blur Multiplier controller. Returns undefined if not Image Motion Blur Multiplier controller has been assigned to the node.

setImageBlurMultiplier <node> <time> <number>

Sets the node's Image Motion Blur Multiplier value at the specified time to the specified value

setImageBlurMultController <node> <controller>

Sets the node's Image Motion Blur Multiplier controller to the specified controller

setMotBlur <node> <integer>

Sets which type of motion blur to use for node. If <integer> = 1, None. If <integer> = 2, Object Motion Blur. If <integer> = 3, Image Motion Blur.

setRenderable <node> <boolean>

Sets whether the node is renderable. If <boolean> is true, node is renderable. If <boolean> is false the node is not renderable.

getRenderID <node>

Returns the RenderID of the node. A value of 65535 is returned if the scene has not yet been rendered, or the node is not renderable. The RenderIDs of the nodes are output to the NODE_RENDER_ID g-buffer channel by the renderer.

setRenderID <node> <integer>

Sets the RenderID of the node to the specified value. This value is not "sticky" - it is not saved with the scene, and it will be replaced by the renderer when the next render occurs.

Group-Related Methods

group <node> [ name:<string> ] [ prefix:<string> ] \

[ select:<boolean> ] -- mapped

Makes a group of the given nodes and returns the group node. You can optionally specify the group name or group name prefix. Not specifying a name or specifying a group name prefix ensures that the group name assigned is unique. Specifying select:true selects the group after it is made.

For example:

group $box* name:"boxes"

makes a group of all box*'s named "boxes".

group selection

groups current selection.

ungroup <group_head_node> -- mapped

Ungroups one level of a group node.

For example:

ungroup $group01

ungroups group $group01

explodeGroup <group_head_node> -- mapped

Ungroups all levels in a group node.

isGroupHead <node>

Returns true if node is group head, false otherwise.

isGroupMember <node>

Returns true if node is in a group, false otherwise.

isOpenGroupMember <node>

Returns true if <node> is a member of a group, and that group is open.

isOpenGroupHead <node>

Returns true if <node> is the head of a group, and that group is open.

setGroupOpen <group_head_node> <boolean>

Sets whether the group is set as open or closed. If <boolean> is true, the group is set as open. If <boolean> is false the group is closed.

*** Use the following methods with care. You can place nodes in states that are impossible to accomplish using the 3ds max user interface. ***

setGroupMember <node> <boolean>

Sets whether the node is a group member or not. If <boolean> is true, node is set as a group member. If <boolean> is false, and the node is a group member, the node is set as not being a group member and is unlinked from the group head.

Notes: If you set a node to be a group member using this method, you need to set the node to be a child of a group head. Otherwise, the node name is not shown in the Select By Name dialog. For example:

setGroupHead $dummy01 true

append $group03.children $dummy01

setGroupHead <node> <boolean>

Sets whether the node is flagged as a group head or not. If <boolean> is true, node is flagged as a group head. If <boolean> is false, the node is set as not being a group head.

Notes: 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

Node Viewport State Methods

hide <node> -- mapped

unhide <node> -- mapped

freeze <node> -- mapped

unfreeze <node> -- mapped

flagForeground <node> <boolean> -- mapped

Controls the disposition of scene nodes in the viewport foreground/background planes, so you can influence interactive performance on a node. Nodes placed in the foreground plane are redrawn individually and so interactive changes to them through spinners in scripted rollout panels are much faster.

The boolean argument puts the scene node(s) into the foreground plane if true, or into the background plane if false. You should be judicious in putting nodes in the foreground plane, because putting too many objects in the foreground plane reduces the foreground plane's effectiveness. Remember to unflag objects when you don't need to interactively control them any more.

getTrajectoryOn <node>

Returns true if Trajectory is shown for the node, false otherwise.

setTrajectoryOn <node> <boolean>

Sets whether Trajectory is shown for the node. If <boolean> is true, Trajectory is shown. If <boolean> is false, Trajectory is not shown.

isBoneOnly <node>

Returns true if the node's showLinksOnly property is true.

getCVertMode <node>

Returns true if node is displayed using vertex colors in shaded viewports, false otherwise.

setCVertMode <node> <boolean>

Sets whether to display the effect of assigned vertex colors for the node in shaded viewports. If <boolean> is true, node is displayed using vertex colors. If <boolean> is false, node is displayed using the material or wireframe color.

getShadeCVerts <node>

Returns true if the vertex color display for the node is shaded in the viewports, false otherwise.

setShadeCVerts <node> <boolean>

Sets whether the vertex color display for the node is shaded in the viewports. When true, the colors are unshaded and appear in their pure RGB values. When false, the colors appear like any other assigned color in the viewports.

Node Selection Methods

clearSelection()

clearNodeSelection [ redraw:<boolean> ]

Deselects all currently selected scene nodes. Scene is redrawn unless redraw:false is specified.

deselect <node> -- mapped

Deselects the given node(s).

For example:

deselect $box*

deselects all items whose names start with "box".

deselectNode <node>

Deselects a single node

select <node> -- mapped

Deselects any currently selected objects and then selects the node(s) you specified.

selectMore <node> -- mapped

Adds the node(s) to the set of selected objects. If you want to build a set of selected objects from scratch in a loop, you can use clearSelection() to clear the selection before entering the loop, and use selectMore() in the loop to add objects to the set of selected objects.

Modifier Stack Related Methods

validModifier [ <node> | <objectset> | <group> ] <modifier>

Tests whether a particular modifier may be added the given <node> or to all of the objects in the objectset or group. Returns true if so, false if not.

The validModifier() method operates exactly as does the Modify panel in determining modifier applicability. Any modifier that takes a deformable object will return true for all scene objects except Helpers. This corresponds to the Modify panel's behavior of allowing modifiers such as Bend, Taper, etc. to be applied to lights and cameras, space warp objects, etc., as well as geometry types like box, sphere, etc., but not helpers such as dummys or bones.

The validModifier() method will return true if an empty <objectset> is specified, or if a <group> is specified and the modifier is valid for all members of the group. In these cases, applying the modifier using the addModifier() method will fail, because the <objectset> is empty in the first case, or because the modifier cannot be applied to the dummy object that is the parent object of the objects in the group. You will need to test for these conditions in your script, or use the modPanel.addModToSelection() method described in Modify Panel.

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 the node is currently selected and open in the Modify panel at the desired sub-object level. You can use the 3ds max System global variable, subObjectLevel to test and set the level for the object currently open in the Modify panel. For example:

max modify mode -- open mod panel

select $box01 -- select box01 into mod panel

subObjectLevel = 3 -- subobject level to Face

addModifier $box01 (ffd_2x2x2()) -- add FFD mod to those faces

If <node> is a collection, an instance of the modifier is placed on each of the nodes in the collection. Unlike interactively applying a modifier to a selection, the position and size of each modifier instance's gizmo corresponds to position and size of the node the modifier instance is applied to. To apply a modifier to a collection in the same manner that 3ds max applies modifiers, use the modPanel.addModToSelection() method described in Modify Panel.

Also see Modifier and SpacewarpModifier for more details.

deleteModifier <node> <modifier_or_index> -- mapped

Lets you delete modifiers from the modifier stack. Takes either a modifier value which is present on the <node> stack, or an index specifying the index of the modifier to delete, counting from the top of the stack.

collapseStack <node> -- mapped

Collapses the modifiers out of a stack, leaving a resultant editable mesh as the base object of the node(s). If there are no modifiers in the stack when this is called, no action is taken. If you want to force an object to be an editable mesh, use the function convertToMesh().

Node Modifier Transform Context Methods

getModContextTM <node> <modifier>

Returns a Matrix3 value giving the modifier's context transform for the local coordinates used in modifier sub-object gizmos. Accessing the transform properties of a modifier sub-object such as a gizmo or a center in MAXScript yields values that are relative to that modifier's context transform, equivalent to the values shown in track view for those properties. If the modifier is not operating on a sub-object selection, such as a face or vertex selection, or if the modifier was interactively applied to an object selection, this context TM is the local coordinate space of the object itself. However, if the modifier is operating on either an object selection set or a sub-object selection, the context transform gives the position and orientation of that selection, and so you can use the getModContextTM() function to get the world-space transform properties of any of its sub-objects.

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 Modifier Sub-Object Transform Properties for examples of using the above methods.

Node Conversion Methods

convertToMesh <node> -- mapped

This function converts appropriate scene object types into Editable Meshes. It is similar to collapseStack() in that it will remove all modifiers present, but unlike collapseStack() it will always replace the base object with an editable mesh version, even if there are no modifiers present.

convertToMesh() can be applied to any object that an Edit Mesh modifier can work on, such as geometry and shapes, but not helpers, space warps, lights, etc. If the object cannot be converted, the function returns undefined.

convertToSplineShape <node> -- mapped

Converts the given scene node to a SplineShape object. If the object cannot be converted (typically, if it is not a shape), the function returns undefined. Any modifiers present will be collapsed. The collapseStack() function can also be used as can the collapse button in the modifier stack dialog in 3ds max; both generate a SplineShape, but will only do so if there is at least one modifier present.

canConvertTo <node> <class>

Allows you to test whether a given node is convertible into a given class. Returns true or false. For example:

if canConvertTo $foo NURBSSurface then ...

The kinds of classes you can convert objects to are the generic editable forms including Mesh, SplineShape, NURBSCurve, NURBSSurface, etc.

convertTo <node> <class> -- mapped

This function is a general form of the existing specific conversion functions such as convertToMesh(), convertToSplineShape(), etc. For example, convertToSplineShape() can be written:

convertTo $circle01 SplineShape

If the conversion is not supported, the function returns the value undefined.

convertToNURBSSurface <node> -- mapped

convertToNURBSCurve <node> -- mapped

These functions work on those primitive geometry and shape classes that support conversion to NURBS (such as boxes, spheres, circles, lines, etc.). If an object does not support conversion, the function returns undefined.

Node Utility Methods

isDeleted <MAXWrapper_object>

This function yields the result true if the object has been deleted and false if it still exists in the scene. Using the function only makes sense in situations where references to 3ds max objects are held in variables or arrays or passed as parameters and you want to determine whether the object has been deleted from the scene. Performing an operation on a deleted 3ds max object referenced in a variable or array otherwise generates an exception. Any kind of 3ds max object can be tested in this way, scene objects, modifiers, controllers, materials, etc.

For example:

sel = selection as array -- snapshot selection

...

-- <one or more objects in the selection are deleted,

-- by the user or other scripts>

...

for obj in sel

where not isDeleted obj do

move obj [10,0,0]

distance <node> <node>

Computes the distance between the pivot points of the two specified nodes.

intersectRay <node> <ray>

Computes the closest intersection of the ray and the surface of the given node. Returns another Ray which defines the position of intersection in 3D space and the surface normal direction vector at that point. The intersection test respects the face normals of the node, i.e. if a face's normal points away from the ray's source, an intersection test is not performed on that face. intersectRay() works if the world state of the node (the state of the node at the top of the node's stack) has a surface, such as an editable mesh, a Standard, Extended, or Compound Primitive, or a Patch or NURBS surface object. Splines and NURBS curves do not have a surface. Returns undefined if the ray doesn't intersect the node, the faces it does intersect point away from the ray's position, or the node does not have a surface.

intersectRayEx <node> <ray>

Takes a ray and computes the closest intersection to the surface of the given node. It returns an array with the following three elements.

A Ray defining the position of intersection in 3-space and the surface normal direction vector at the point.

The index of the face the ray intersects with

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:

Example:

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

tv2 = getTVert s tf.y

tv3 = getTVert s tf.z

--

-- Calculate the texture vertices at point of intersection from

-- the barycentric coordinates

tv = tv1*arr[3].x + tv2*arr[3].y + tv3*arr[3].z

--

-- Delete the modifier deleteModifier s 1 intersects <node> <node>

Returns true if the bounding boxes of the two specified nodes overlap, or false if they do not overlap.

printStack <node>

Prints a representation of the current modifier stack for the given node.

Node User Properties

getUserProp <node> <key_string>

Retrieves the node's user property with the given key as a string. <key_string> is either a String or a Name value. If the key does not exist, a value of undefined is returned.

setUserProp <node> <key_string> <value>

Sets the node's user property with the given key to the given value.

getUserPropBuffer <node>

Retrieves the entire user property buffer as a string containing all the user property settings. This is effectively the contents of the User Defined Properties box in the 3ds max Object Properties dialog.

setUserPropBuffer <node> <string>

Sets the user property buffer to the given string.

See Node User-Defined Properties and Methods for more information on these methods.

Inverse Kinematics Properties

The following methods get and set the node's IK values as seen in the Hierarchy panel, Object Parameters rollout.

getRotTaskWeight <node>

Returns the rotation binding weight for the node.

setRotTaskWeight <node> <float>

Sets the rotation binding weight for the node.

getPosTaskWeight <node>

Returns the position binding weight for the node.

setPosTaskWeight <node> <float>

Sets the position binding weight for the node.

getTaskAxisState <node> <pos_or_rot_integer> <axis_integer>

Returns true or false to indicate if the specified axis is turned on for position or rotation binding. If an axis is turned off, the specified axis is no longer influenced by the follow object or the IK Controller Position end effector. <pos_or_rot_integer> sets whether the method returns the position state or the rotation state: 0 specifies position; 1 specifies rotation. <axis_integer> sets the axis to check: 0 specifies X, 1 specifies Y, 2 specifies Z.

setTaskAxisState <node> <pos_or_rot_integer> <axis_integer> <boolean>

Sets the axis state for position or rotation binding to the specified boolean value. See getTaskAxisState() for a description of the parameters.

mirrorIKConstraints <node> <axis_integer> <pos_or_rot_integer>

Mirrors the specified IK constraints on the specified node's transform controller about the specified axis. <axis_integer> specifies the axis of reflection: 0 for X, 1 for Y, 2 for Z. <pos_or_rot_integer> specifies which type of constraints are being mirrored: 0 for position, 1 for rotation.

nodeIKParamsChanged <node>

Call this method when one of the node level IK parameters has been changed.

OKToBindToNode <ik_node> <node>

Returns true if the <ik_node> can be bound to the <node> as a follow object, false otherwise. If the <ik_node> is not part of an IK system, this method always returns true. This method tests <node> to see if its transform is in any way already dependent on the IK system, and returns false if it is.

Miscellaneous Methods

classOf <node>

Returns the class of the world state of the node (the state of the node at the top of its stack). If no modifiers are applied to the base object, the class returned is the class of the base object. If modifiers are applied to the base object, the class returned is the class of the node as it exits the last modifier. For example, if you apply a Bend modifier to a Box, the Bend modifier converts the incoming Box primitive to a mesh, and the class returned by classOf is Editable_Mesh. You can get the class of the base object in all cases by using classOf <node>.baseObject.

isPointSelected <node> <point_index>

Returns true if the specified point is selected, false if not. The definition of a 'point' varies depending on the object type. For meshes, it is the mesh vertex. For a spline, it is the knot. For NURBS objects, it is the vertex or control point.

pointSelection <node> <point_index>

Returns a floating point weighted point selection if the object supports soft selections. Most object types just return 1.0 if the point is selected and 0.0 if not. Only NURBS and Editable Mesh objects currently support weighted point selection.

nodeInvalRect <node>

Invalidates the rectangle in the viewports that the node is occupying. Rectangles flagged as invalid will be update on the next screen redraw.

stopCreating <node>

This method stops the creation of the current object, if any. This method is primarily used to ensure that a NURBS objects is fully created, which it until the creation is stopped. This method will also deactivated any activated object create buttons in the Create panel.

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

Value Common Properties, Operators, and Methods

General Node Properties

Node Transform Properties

Node User-Defined Properties and Methods

Nested Object Properties

Class and Object Inspector Functions

Dynamic Properties

Node Subclasses

NURBS Node Properties and Methods


General Node Properties

All the properties listed here are accessible on any node subclass. Unless otherwise noted, these properties can not be animated.

<node>.name String default: varies

Get or set the scene object's name.

<node>.baseObject A subclass of Node default: varies -- read-only

Retrieve the base object in a scene node. This has relevance in nodes that have modifiers present that change the node type as it is processed up the stack. For example, a line with an extrude modifier starts out as a Shape and turns into an Editable Mesh at the top of the stack, its so-called world state. The baseObject property gives you access to the base object in the modifier stack. Because the classOf() function on scene node objects returns the class of the world state object (the top of the stack), you can use the baseObject property to determine the class of the original object used to create the node. This property is read-only.

<node>.material Material default: undefined

Get or set the object's material.

<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 NodeChildrenArray Values. A NodeChildrenArray can be accessed using normal MAXScript array indexing and can be sequenced over in a for loop or with collection-mapped functions, for example:

c = $foo.children[i]

move $foo.children [10,10,10]

for c in $baz.children do print c

You can get the number of children via the count property:

num_children = $foo.children.count

You cannot directly set a child by indexing into NodeChildrenArray, but you can append new children using the append() function and delete children using the deleteItem() function:

$foo.children[$foo.children.count+1]=$baz -- does not work

append $foo.children $baz -- works

deleteItem $foo.children $baz -- removes $baz as child

The ordering of child indexes corresponds to the ordering shown in the 3ds max hierarchy view, which is the order in which the children were added to the parent.

<node>.mesh TriMesh

For scene nodes or base objects that are Editable Mesh objects, or are convertable to Editable Mesh objects, this property yields a TriMesh containing a copy of the source object's mesh after any modifiers have been applied, but before any space warps have been applied. This property is read-only unless the scene node or base object is an Editable Mesh object, in which case the specified TriMesh replaces the base object. See Editable_Mesh : GeometryClass and TriMesh : Value for more information on TriMesh and Editable Mesh.

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.

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

<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>.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. The default coordsys is world. The pos, rotation, and scale properties of a node are aliases to the corresponding subcontroller for the node's transform controller. If the transform controller does not have one of these subcontrollers, accessing the corresponding node property will result in an "Unknown property" error message. For example, the LookAt controller does not have a Rotation subcontroller, and the IK controller does not have any subcontrollers. You can still access the transform values using the Matrix3 properties of the node's transform property, for example, objpos=obj.transform.translationpart.

<node>.transform : Matrix3 -- can read/write to. If written to,

: the Matrix3 value is decomposed into its

: position, rotation, and scale values, and these

: values are stored in the respective position,

: rotation, and scale controllers, if those

: controllers exist and can be written to.

<node>.pos : Point3 -- can use .position synonym throughout

<node>.pos.controller : Controller—can use .track synonym throughout

<node>.pos.isAnimated : Boolean, read-only—true if position is animated

<node>.pos.keys : MAXKeyArray

<node>.pos.track : Controller—synonym of .pos.controller

<node>.rotation : Quat

<node>.rotation.x_rotation : X rotation of node

<node>.rotation.y_rotation : Y rotation of node

<node>.rotation.z_rotation : Z rotation of node

<node>.rotation.controller : Controller—can use .track synonym throughout

<node>.rotation.isAnimated : Boolean, read-only—true if rotation is animated

<node>.rotation.keys : MAXKeyArray

<node>.rotation.track : Controller—synonym of .rotation.controller

<node>.scale : Point3 -- fraction

<node>.scale.controller : Controller—can use .track synonym throughout

<node>.scale.isAnimated : Boolean, read-only—true if scale is animated

<node>.scale.keys : MAXKeyArray

<node>.scale.track : Controller—synonym of .scale.controller

<node>.dir : Point3 -- local z-axis direction vector

Rotates node so that the node's Z axis points in the specified direction. The node is rotated around its Z axis such that the Y axis points as much as possible in the world -Z direction.

<node>.max : Point3, read-only—max coordinates of node's bounding box

<node>.min : Point3, read-only—min coordinates of node's bounding box

<node>.center : Point3 -- coordinates of center of node's bounding box

<node>.transform : Matrix3 -- node's main transformation matrix

Note that rotation in the internal transformation matrices is left-handed in contradiction to the 3ds max user interface and MAXScript. Take care when mixing rotation derived from these matrices and rotation used in rotation-related functions or from rotation properties.

<node>.pivot : Point3 -- node's pivot point position

<node>.objectOffsetPos : Point3

<node>.objectOffsetRot : Quat

<node>.objectOffsetScale : Point3

Node geometry's position, rotation, and scale offset from the pivot in world coordinates.

<node>.objectTransform : Matrix3, read-only

Node geometry's offset in world coordinates.

See also

Using Node Transform Properties


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

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.

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.

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

)

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]


Node User-Defined Properties and Methods

The functions described in this topic give you access to scene object user properties, accessible in the 3ds max user interface in the User Defined tab in the Object Properties Dialog. There are two ways to access and set the user defined properties in the Object Properties dialog—either as one single string representing the entire contents or as key/property pairs in the form:

<key1> = <property1>

<key2> = <property2>

...

where the keys are identifiers (Name or String values) and the properties can be numbers, booleans (true/false) or text strings. There are two MAXScript methods for setting and getting individual keyed properties, and two methods that let you treat the property text as a single big string.

Caution: There is currently a bug in the get/set property functions in the 3ds max SDK for text string properties that truncates retrieved string properties at the first space character in the string value.

The <node> methods are:

getUserProp <node> <key_string>

retrieves the node's user property with the given key as a string. <key_string> is either a String or a Name value. If the key does not exist, a value of undefined is returned.

setUserProp <node> <key_string> <value>

sets the node's user property with the given key to the given value

getUserPropBuffer <node>

retrieves the entire user property buffer as a string containing all the user property settings. This is effectively the contents of the User Defined Properties box in the 3ds max Object Properties dialog

setUserPropBuffer <node> <string>

sets the user property buffer to the given string

The following two example code fragments save and load user properties for objects in a scene.

The first code fragment creates a file and loops through all objects outputting for each the object name and user property buffer string. Note that the object name goes out in a form that will come back in (via a readValue()) as a direct reference to a scene object. Also, the user property string is output using print() so it will be in a quoted form to be read as one (long) string literal by a corresponding readValue().

The second code fragment reads in the file created by the first piece and applies the user properties to any same-named object in the current scene. Note that readValue() can read in pathnames ($<name>) and will yield either the named scene object or undefined if the named object is not in the scene. The readValue() function can also read in a multiline string literal in one pass.

-- 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 Node : MAXWrapper. The property listings show name, type and constructor default value. The following list displays the 3ds max node subclasses:

GeometryClass

Shape

Light

Camera

Helper

SpacewarpObject


GeometryClass : Node

The following list shows the 3ds max geometry class objects:

Standard Primitives

Box

Cone

Cylinder

Geosphere

Plane

Pyramid

Sphere

Teapot

Torus

Tube

Extended Primitives

Capsule

ChamferBox

ChamferCyl

C_Ext

Gengon

Hedra

L_Ext

OilTank

Prism

RingWave

Spindle

TargetObject

Torus_Knot

Compound Objects

OldBoolean

Boolean2

Conform

Connect

Loft

Morph

Scatter

ShapeMerge

Terrain

Particle Systems

Blizzard

PArray

PCloud

Snow

Spray

SuperSpray

Patch Grids

QuadPatch

TriPatch

NURBS Surfaces

NURBSSurf

Point_Surf

Dynamics Objects

Damper

Spring

Doors

BiFold

Pivot

SlidingDoor

Windows

Awning

Casement

Fixed

Pivoted

Projected

SlidingWindow

AEC Extended Objects

Terrain

Foliage

Railing Wall_GeometryClass

Stairs

L_Type_Stair

Spiral_Stair

Straight_Stair

U_Type_Stair

Miscellaneous

LinkComposite

Host_Composite


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

Capsule

ChamferBox

ChamferCyl

Cone

Cylinder

C_Ext

Gengon

Geosphere

Hedra

L_Ext

OilTank

Plane

Prism

Pyramid

RingWave

Sphere

Spindle

TargetObject

Teapot

Torus

Torus_Knot

Tube


Box : GeometryClass

Constructor

box ...

Properties

<Box>.length Float default: 25.0 -- animatable

Sets the length of the box object.

<Box>.width Float default: 25.0 -- animatable

Sets the width of the box object.

<Box>.height Float default: 25.0 -- animatable

Sets the height of the box object.

<Box>.lengthsegs Integer default: 1 -- animatable, alias: Length_Segments

Sets the number of divisions along the length of the object.

<Box>.widthsegs Integer default: 1 -- animatable, alias: Width_Segments

Sets the number of divisions along the width of the object.

<Box>.heightsegs Integer default: 1 -- animatable, alias: Height_Segments

Sets the number of divisions along the height of the object.

<Box>.mapcoords Boolean default: false

When on, generates coordinates for applying mapped materials to the box.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


C_Ext : GeometryClass

Constructor

c_ext ...

Note: This class is not available in 3D Studio VIZ.

Properties

<C_Ext>.Back_Length Float default: 0.0 -- animatable

Sets the length of the back edge.

<C_Ext>.Side_Length Float default: 0.0 -- animatable

Sets the length of the side edge.

<C_Ext>.Front_Length Float default: 0.0 -- animatable

Sets the length of the front edge.

<C_Ext>.Back_Width Float default: 0.0 -- animatable

Sets the width of the back edge.

<C_Ext>.Side_Width Float default: 0.0 -- animatable

Sets the width of the side edge.

<C_Ext>.Front_Width Float default: 0.0 -- animatable

Sets the width of the front edge.

<C_Ext>.height Float default: 0.0 -- animatable

Sets the overall height of the object.

<C_Ext>.Back_Segments Integer default: 1 -- animatable

The number of segments along the back edge of the object.

<C_Ext>.Side_Segments Integer default: 1 -- animatable

The number of segments along the side edge of the object.

<C_Ext>.Front_Segments Integer default: 1 -- animatable

The number of segments along the front edge of the object.

<C_Ext>.Width_Segments Integer default: 1 -- animatable

The number of segments along the width of the object.

<C_Ext>.Height_Segments Integer default: 1 -- animatable

The number of segments along the height of the object.

Notes

The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Capsule : GeometryClass

Constructor

capsule ...

Properties

<Capsule>.radius Float default: 15.0 -- animatable

The radius of the capsule.

<Capsule>.height Float default: 25.0 -- animatable

The height of the capsule.

<Capsule>.heighttype Integer default: 1

Set what .height specifies:

0- Overall

1- Centers (not including domed caps)

<Capsule>.sides Integer default: 24 -- animatable

Sets the number of sides around the capsule. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off.

<Capsule>.heightsegs Integer default: 1 -- animatable; alias: height_segments

The number of divisions along the capsule's major axis.

<Capsule>.smooth Boolean default: true -- animatable

When on, blends the faces of the capsule, creating a smooth appearance in rendered views.

<Capsule>.smooth_on Integer default: 1 -- animatable

Smooth_on is an integer alias of smooth:

0- off

1- on

<Capsule>.sliceon Boolean default: false—animatable

Turns on/off the Slice function.

<Capsule>.slice_on Integer default: 0 -- animatable

Slice_on is an integer alias of sliceon:

0- off

1- on

<Capsule>.slicefrom Float default: 0.0 -- animatable, angle; alias: slice_from

Sets the starting angle (on the local Z-axis) for slicing.

<Capsule>.sliceto Float default: 0.0 -- animatable, angle; alias: slice_to

Sets the angle (on the local Z-axis) to slice to.

<Capsule>.mapCoords Boolean default: false

When on, sets up the required coordinates for applying mapped materials to the capsule.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


ChamferBox : GeometryClass

Constructor

chamferBox ...

Properties

<ChamferBox>.length Float default: 0.1 -- animatable

The length of the object.

<ChamferBox>.width Float default: 0.1 -- animatable

The width of the object.

<ChamferBox>.height Float default: 0.1 -- animatable

The height of the object.

<ChamferBox>.Fillet Float default: 0.01 -- animatable

Slices off the edges of the chamferbox. The higher the number, the more filleted the chamferbox becomes.

<ChamferBox>.Length_Segments Integer default: 1 -- animatable

The number of divisions along the length of the object.

<ChamferBox>.Width_Segments Integer default: 1 -- animatable

The number of divisions along the width of the object.

<ChamferBox>.Height_Segments Integer default: 1 -- animatable

The number of divisions along the height of the object.

<ChamferBox>.Fillet_Segments Integer default: 3 -- animatable

The number of segments in the filleted edges of the box. Adding fillet segments increases the edge roundness.

Notes

The Generate Mapping Coordinates and Smooth properties are not accessible to MAXScript in 3ds max 4.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


ChamferCyl : GeometryClass

Constructor

chamferCyl ...

Properties

<ChamferCyl>.radius Float default: 0.0 -- animatable

The radius of the chamfered cylinder.

<ChamferCyl>.height Float default: 0.0 -- animatable

The dimension along the central axis. Negative values create the chamfered cylinder below the construction plane.

<ChamferCyl>.Fillet Float default: 0.0 -- animatable

Slices off the edges of the chamfered cylinder. The higher the number, the more filleted the cylinder becomes.

<ChamferCyl>.Height_Segments Integer default: 1 -- animatable

The number of divisions along the corresponding axis.

<ChamferCyl>.Fillet_Segments Integer default: 1 -- animatable

The number of segments in the filleted edges of the box. Adding fillet segments curves the edges, producing a chamfered cylinder.

<ChamferCyl>.sides Integer default: 12 -- animatable

The number of sides around the chamfered cylinder. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off.

<ChamferCyl>.Cap_Segments Integer default: 1 -- animatable

The number of concentric divisions along the center of the chamfered cylinder's top and bottom

<ChamferCyl>.Smooth Boolean default: true—animatable

When on, blends the faces of the chamfered cylinder, creating a smooth appearance in rendered views.

<ChamferCyl>.Smooth_On Integer default: 1 -- animatable

Integer alias for .smooth:

0- off

1- on

<ChamferCyl>.SliceOn Boolean default: false -- animatable

Turn on/off the slice function.

<ChamferCyl>.Slice_On Integer default: 0 -- animatable

Integer alias for .slice_on:

0- off

1- on

<ChamferCyl>.Slice_From Float default: 0.0 -- animatable, angle

Sets the starting angle (on the local Z-axis) for slicing.

<ChamferCyl>.Slice_To Float default: 0.0 -- animatable, angle

Sets the angle (on the local Z-axis) to slice to.

Notes

The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Cone : GeometryClass

Constructor

cone ...

Properties

<Cone>.radius1 Float default: 15.0 -- animatable, alias: Radius_1

The first radius of the cone.

<Cone>.radius2 Float default: 0.0 -- animatable, alias: Radius_2

The second radius of the cone.

<Cone>.height Float default: 25.0 -- animatable

Height along the central axis. Negative values create the cone below the construction plane.

<Cone>.heightsegs Integer default: 5 -- animatable, alias: Height_Segments

The number of divisions along the cone's major axis.

<Cone>.capsegs Integer default: 1 -- animatable, alias: Cap_Segments

The number of concentric divisions around the center of the cone's top and bottom.

<Cone>.sides Integer default: 24 -- animatable

The number of sides around the cone. Higher numbers shade and render as true circles with Smooth selected. Lower numbers create regular polygonal objects with Smooth off.

<Cone>.smooth Boolean default: true -- animatable

When on, blends the faces of the cone, creating a smooth appearance in rendered views.

<Cone>.slice Boolean default: false -- animatable, alias: sliceon

Turns on/off slice function.

<Cone>.Slice_On Integer default: 0

Integer alias for .slice:

0- off

1- on

<Cone>.sliceFrom Float default: 0.0 -- animatable, angle, alias: Slice_From

Sets the starting angle (on the local Z-axis) for slicing.

<Cone>.sliceTo Float default: 0.0 -- animatable, angle, alias: Slice_To

Sets the angle (on the local Z-axis) to slice to.

<Cone>.mapCoords Boolean default: false

When on, sets up required coordinates for applying mapped materials to the cone.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Cylinder : GeometryClass

Constructor

cylinder ...

Properties

<Cylinder>.radius Float default: 15.0 -- animatable

The radius of the cylinder.

<Cylinder>.height Float default: 25.0 -- animatable

Height along the central axis. Negative values create the cylinder below the construction plane.

<Cylinder>.heightsegs Integer default: 1 -- animatable, alias: Height_Segments

The number of divisions along the cylinder's major axis.

<Cylinder>.capsegs Integer default: 1 -- animatable, alias: Cap_Segments

The number of concentric divisions around the center of the cylinder's top and bottom.

<Cylinder>.sides Integer default: 24 -- animatable

The number of sides around the cylinder. With Smooth on, higher numbers shade and render as true circles. With Smooth off, lower numbers create regular polygonal objects.

<Cylinder>.smooth Boolean default: true -- animatable

When on, the faces of the cylinder are blended together, creating a smooth appearance in rendered views.

<Cylinder>.slice Boolean default: false -- animatable, alias: sliceon

Turns on/off slice function.

<Cylinder>.Slice_On Integer default: 0

Integer alias for .slice:

0- off

1- on

<Cylinder>.sliceFrom Float default: 0.0 -- animatable, angle, alias: Slice_From

Sets the starting angle (on the local Z-axis) for slicing.

<Cylinder>.sliceTo Float default: 0.0 -- animatable, angle, alias: Slice_To

Sets the angle (on the local Z-axis) to slice to.

<Cylinder>.mapCoords Boolean default: false

When on, sets up the required coordinates for applying mapped materials to the cylinder.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Gengon : GeometryClass

Generic polygon.

Constructor

gengon ...

Properties

<Gengon>.sides Integer default: 5 -- animatable

The number of sides around the gengon. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off.

<Gengon>.radius Float default: 0.0 -- animatable

The radius of the gengon.

<Gengon>.Fillet Float default: 0.0 -- animatable

The width of the fillet area.

<Gengon>.height Float default: 0.0 -- animatable

Height along the central axis. Negative values create the gengon below the construction plane.

<Gengon>.Side_Segments Integer default: 1 -- animatable

The number of divisions around the gengon.

<Gengon>.Height_Segments Integer default: 1 -- animatable

The number of divisions along the gengon's major axis.

<Gengon>.Fillet_Segments Integer default: 1 -- animatable

The number of divisions for the edge filleting. The higher this setting, the rounder the fillet appears.

Notes

The Generate Mapping Coordinates and Smooth properties are not accessible to MAXScript in 3ds max R4.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Geosphere : GeometryClass

Constructor

geosphere ...

Properties

<GeoSphere>.creationMethod Integer default: 1 -- alias: Creation_Method

Sets the creation method:

0- Diameter (Draws a geosphere from edge to edge.)

1- Center (Draws a geosphere from the center out.)

<GeoSphere>.typeInPos Point3 default: [0,0,0]

The point3 position of the geosphere.

<GeoSphere>.typeInRadius Float default: 25.0

The radius of the geosphere.

<GeoSphere>.radius Float default: 25.0 -- animatable

The radius of the geosphere.

<GeoSphere>.segs Integer default: 4 -- animatable, alias: segments

The total number of faces in the geosphere. The number of faces in a geosphere is equal to the sides of the base polyhedron times the segments squared.

Lower segment values work best. Using the maximum segment value of 200 can generate up to 800,000 faces, impairing performance.

<GeoSphere>.baseType Integer default: 2 -- alias: Base_Type

Sets the type of basic geometry for the geosphere:

0- 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.)

1- 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.)

2- Icosa (Based on a 20-sided icosahedron. The facets are all equally sized equilateral triangles. The sphere can be divided into any number of equal segments, based on multiples and divisions of 20 faces.)

<GeoSphere>.smooth Boolean default: true -- animatable

When on, applies smoothing groups to the surface of the sphere.

<GeoSphere>.hemisphere Boolean default: false -- animatable

When on, creates a half-sphere.

<GeoSphere>.baseToPivot Boolean default: false -- alias: Base_to_Pivot

Sets the pivot point location. When on, the pivot is at the bottom of the sphere. When off, the pivot is at the center of the sphere. This option has no effect when Hemisphere is on.

<GeoSphere>.mapCoords Boolean default: false -- alias: Generate_mapping_coords

When on, applies default mapping coordinates to the geosphere.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Hedra : GeometryClass

Constructor

hedra ...

Properties

<Hedra>.family Integer default: 0

Sets the type of polyhedron to create:

0- Tetra (Creates a tetrahedron)

1- Cube/Octa (Creates a cubic or octahedral polyhedron, depending on parameter settings.)

2- Dodec/Icos (Creates a dodecahedron or icosahedron, depending on parameter settings.)

3- Star1 (Creates a star-like polyhedra.)

4- Star2 (Creates a different star-like polyhedra.)

<Hedra>.p Float default: 0.0 -- animatable, alias: Q_Value

<Hedra>.q Float default: 0.0 -- animatable, alias: P_Value

Interrelated parameters that provide a two-way translation between the vertices and facets of a polyhedron. They share the following:

  • Range of possible values is 0.0 through 1.0.

  • The combined total of the P and Q values can be equal to or less than 1.0.

  • Extremes occur if either P or Q is set to 1.0; the other is automatically set to 0.0.

  • Midpoint occurs when both P and Q are 0.

    In the simplest terms, P and Q change the geometry back and forth between vertices and facets. At the extreme settings for P and Q, one parameter represents all vertices, the other represents all facets. Intermediate settings are transition points, with the midpoint an even balance between the two parameters.

<Hedra>.scalep Float default: 1.0 -- animatable

Controls the axis of reflection for the p facet of a polyhedron.

<Hedra>.scaleq Float default: 1.0 -- animatable

Controls the axis of reflection for the q facet of a polyhedron.

<Hedra>.scaler Float default: 1.0 -- animatable

Controls the axis of reflection for the r facets of a polyhedron.

<Hedra>.P_Scale Float default: 100.0

Controls the axis of reflection for the p facet of a polyhedron.

<Hedra>.Q_Scale Float default: 100.0

Controls the axis of reflection for the q facet of a polyhedron.

<Hedra>.R_Scale Float default: 100.0

Controls the axis of reflection for the r facets of a polyhedron.

<Hedra>.vertices Integer default: 0 -- alias: vertType

Sets the internal geometry of each facet of the polyhedron:

0- Basic (Facets are not subdivided beyond the minimum.)

1- Center (Each facet is subdivided by placing an additional vertex at its center, with edges from each center point to the facet corners.)

2- Center & Sides (Each facet is subdivided by placing an additional vertex at its center, with edges from each center point to the facet corners, as well as to the center of each edge. Compared to Center, Center & Sides doubles the number of faces in the polyhedron.)

<Hedra>.radius Float default: 25.0 -- animatable

The radius of any polyhedron in current units.

<Hedra>.mapCoords Boolean default: false

When on, sets up required coordinates for applying mapped materials to the hedra.

Notes

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

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


L_Ext : GeometryClass

Constructor

l_ext ...

Note: This class is not available in 3D Studio VIZ.

Properties

<L_Ext>.Side_Length Float default: 0.0 -- animatable

The length of the side edge.

<L_Ext>.Front_Length Float default: 0.0 -- animatable

The length of the front edge.

<L_Ext>.Side_Width Float default: 0.0 -- animatable

The width of the side edge.

<L_Ext>.Front_Width Float default: 0.0 -- animatable

The width of the front edge.

<L_Ext>.height Float default: 0.0 -- animatable

The height of the object.

<L_Ext>.Side_Segments Integer default: 1 -- animatable

Number of segments along the side edge.

<L_Ext>.Front_Segments Integer default: 1 -- animatable

Number of segments along the front edge.

<L_Ext>.Width_Segments Integer default: 1 -- animatable

Number of segments along the width of the object.

<L_Ext>.Height_Segments Integer default: 1 -- animatable

Number of segments along the height of the object.

Notes

The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


OilTank : GeometryClass

Constructor

oilTank ...

Properties

<OilTank>.radius Float default: 0.0 -- animatable

The radius of the oiltank.

<OilTank>.height Float default: 0.0 -- animatable

The height along the central axis. Negative values create the oiltank below the construction plane.

<OilTank>.Cap_Height Float default: 0.0 -- animatable

Sets the height of the convex caps. The minimum value is 2.5% of the Radius setting. The maximum value is the Radius setting, unless the absolute value of the Height setting is less than the double Radius setting, in which case cap height cannot exceed half of the absolute value of the Height setting.

<OilTank>.blend Float default: 0.0 -- animatable

When greater than 0, creates a bevel at the edge of the caps.

<OilTank>.sides Integer default: 12 -- animatable

Sets the number of sides around the oiltank. To create a smoothly rounded object, use a higher number of sides and turn Smooth on. To create an oiltank with flat sides, use a lower number of sides and turn Smooth off.

<OilTank>.Height_Segments Integer default: 1 -- animatable

Sets the number of divisions along the oiltank's major axis.

<OilTank>.Smooth_On Integer default: 1 -- animatable

Turn on/off smooth:

0- off

1- on

<OilTank>.Slice_On Integer default: 0 -- animatable

Turn on/off slice:

0- off

1- on

<OilTank>.Slice_From Float default: 0.0 -- animatable, angle

Sets the starting angle (on the local Z-axis) for slicing.

<OilTank>.Slice_To Float default: 0.0 -- animatable, angle

Sets the angle (on the local Z-axis) to slice to.

Notes

The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Plane : GeometryClass

Constructor

plane ...

Properties

<Plane>.typeinCreationMethod Integer default: 0 -- alias: Creation_Method

Set the creation method:

0- Rectangle (Creates the plane primitive from one corner to the diagonally opposite corner, interactively setting different values for length and width.)

1- Square (Creates a square plane where length and width are equal.)

<Plane>.typeinPos Point3 default: [0,0,0]

Position of the plane in the World Space Coordinate system.

<Plane>.typeinLength Float default: 25.0

Length of the plane object.

<Plane>.typeinWidth Float default: 25.0

Width of the plane object.

<Plane>.length Float default: 25.0 -- animatable

Length of the plane object.

<Plane>.width Float default: 25.0 -- animatable

Width of the plane object.

<Plane>.lsegs Integer default: 4 -- animatable, alias: Length_Segments

Number of divisions along the length of the plane object.

<Plane>.wsegs Integer default: 4 -- animatable, alias: Width_Segments

Number of divisions along the width of the plane object.

<Plane>.density Float default: 1.0 -- animatable

Specifies the factor by which the number of segments in both length and width are multiplied at render time.

<Plane>.renderScale Float default: 1.0 -- animatable, alias: Render_Scale

Specifies the factor by which both length and width are multiplied at render time. Scaling is performed from the center outward.

<Plane>.mapCoords Boolean default: false—alias: Mapping

When on, generates coordinates for applying mapped materials to the box.

Notes

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

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Prism : GeometryClass

Constructor

prism ...

Properties

<Prism>.side1Length Float default: 25.0 -- animatable, alias: Side_1_Length

Sets the length of triangle's first side.

<Prism>.side2Length Float default: 25.0 -- animatable, alias: Side_2_Length

Sets the length of triangle's second side.

<Prism>.side3Length Float default: 25.0 -- animatable, alias: Side_3_Length

Sets the length of triangle's third side.

<Prism>.height Float default: 10.0 -- animatable

The height of the prism's central axis.

<Prism>.side1Segs Integer default: 1 -- animatable, alias: Side_1_Segments

The number of divisions along the first side.

<Prism>.side2Segs Integer default: 1 -- animatable, alias: Side_2_Segments

The number of divisions along the second side.

<Prism>.side3Segs Integer default: 1 -- animatable, alias: Side_3_Segments

The number of divisions along the third side.

<Prism>.heightsegs Integer default: 1 -- animatable, alias: Height_Segments

The number of divisions along the central axis.

<Prism>.mapCoords Boolean default: false

When on, sets up the required coordinates for applying mapped materials to the prism.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Pyramid : GeometryClass

Constructor

pyramid ...

Properties

<Pyramid>.width Float default: 25.0 -- animatable

The width of the pyramid.

<Pyramid>.depth Float default: 25.0 -- animatable

The depth of the pyramid.

<Pyramid>.height Float default: 25.0 -- animatable

The height of the pyramid.

<Pyramid>.widthsegs Integer default: 1 -- animatable, alias: Width_Segments

The number of divisions along the width of the pyramid.

<Pyramid>.depthSegs Integer default: 1 -- animatable, alias: Depth_Segments

The number of divisions along the depth of the pyramid.

<Pyramid>.heightsegs Integer default: 1 -- animatable, alias: Height_Segments

The number of divisions along the height of the pyramid.

<Pyramid>.mapCoords Boolean default: false

When on, sets up required coordinates for applying mapped materials to the pyramid.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


RingWave : GeometryClass

Constructor

ringwave ...

Note: This class is not available in 3D Studio VIZ.

Properties

Note: Some of the properties can be entered using more than one syntax. They are listed together in the following list. Either syntax can be used, they are connected.

<RingWave>.'max diameter' Float default: 500.0 -- animatable; alias: radius

The outside radius of the ringwave.

<RingWave>.'Radius Segs' Integer default: 1 -- animatable; alias: radial_Segments

The segment count between the inner and outer surfaces in the direction of radius.

<RingWave>.'ring width' Float default: 1.0 -- animatable; alias: Ring_Width

The mean ring width as measured inward from the outer radius.

<RingWave>.'ring segments' Integer default: 200 -- animatable; alias: sides

The number of segments in the circumferential direction for both the inner, outer, and end (cap) surfaces.

<RingWave>.height Float default: 0.0 -- animatable

The height of the ringwave along its major axis.

<RingWave>.'Height Segs' Integer default: 1 -- animatable; alias: Height_Segments

The number of segments in the direction of the height.

<RingWave>.Repeat Integer default: 2 -- animatable

Repeat = 0 - Cyclic Growth; 1 - Grow and Stay; 2 - No Growth

<RingWave>.'time on' Integer default: 0 -- animatable; alias: Start_Time

The time where the ringwave appears, and begins to grow.

<RingWave>.'time growing' Integer default: 9600 -- alias: Grow_Time

The time after .'time on' that the ringwave takes to reach full size.

<RingWave>.'display until' Integer default: 16000 -- animatable; alias: End_Time

The time after which the ringwave disappears.

<RingWave>.'Outer Edge Breakup' Boolean default: false -- alias: Outer_Edge_Breakup

Turns on breakup of the outer edge.

<RingWave>.'Major Cycles Outer' Integer default: 1 -- alias: Outer_Edge_Major_Cycles

The number of major waves around the outer edge.

<RingWave>.'Major Cycle Flux Outer' Float default: 0.0 -- animatable; alias: Outer_Edge_Major_Flux

The size of the major waves, expressed as a percentage of the unmodulated width.

<RingWave>.'Major Cycle Flux Per Outer' Integer default: 16000 -- animatable; alias: Outer_Edge_Major_Crawl_Time

The time each major wave takes to move around the outer circumference of the RingWave.

<RingWave>.'Minor Cycles Outer' Integer default: 1 -- alias: Outer_Edge_Minor_Cycles

The number of random-sized smaller waves in each major cycle.

<RingWave>.'Minor Cycle Flux Outer' Float default: 0.0 -- animatable; alias: Outer_Edge_Minor_Flux

The average size of the smaller waves, expressed as a percentage of the unmodulated width.

<RingWave>.'Minor Cycle Flux Per Outer' Integer default: -16000 -- animatable; alias: Outer_Edge_Minor_Crawl_Time

The time each minor wave takes to move across its respective major wave.

<RingWave>.'Inner Edge Breakup' Boolean default: true -- alias: Inner_Edge_Breakup

Turns on the breakup of the inner edge.

<RingWave>.'Major Cycles Inner' Integer default: 11 -- alias: Inner_Edge_Major_Cycles

The number of major waves around the inner edge.

<RingWave>.'Major Cycle Flux Inner' Float default: 25.0 -- animatable; alias: Inner_Edge_Major_Flux

The size of the major waves, expressed as a percentage of the unmodulated width.

<RingWave>.'Major Cycle Flux Per Inner' Integer default: 19360 -- animatable; alias: Inner_Edge_Major_Crawl_Time

The time each major wave takes to move around the inner circumference of the RingWave.

<RingWave>.'Minor Cycles Inner' Integer default: 29 -- alias: Inner_Edge_Minor_Cycles

The average size of the smaller waves, expressed as a percentage of the unmodulated width.

<RingWave>.'Minor Cycle Flux Inner' Float default: 10.0 -- animatable; alias: Inner_Edge_Minor_Flux

The average size of the smaller waves, expressed as a percentage of the unmodulated width.

<RingWave>.'Minor Cycle Flux Per Inner' Integer default: -4320 -- animatable; alias: Inner_Edge_Minor_Crawl_Time

The time each minor wave takes to move across its respective major wave.

<RingWave>.repeats Integer default: 2 -- radio button number

The number of times the ringwave cycle repeats.

<RingWave>.'Mapping Coords' Boolean default: false

When on, assigns mapping coordinates to the ringwave.

<RingWave>.Smoothing Boolean default: false

When on, smooths the surface of the ringwave.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Sphere : GeometryClass

Constructor

sphere ...

Properties

<Sphere>.radius Float default: 25.0 -- animatable

The radius of the sphere.

<Sphere>.segs Integer default: 16 -- animatable, alias: segments

The number of polygonal divisions for the sphere.

<Sphere>.smooth Boolean default: true -- animatable

When on, blends the faces of the sphere, creating a smooth appearance in rendered views.

<Sphere>.hemisphere Float default: 0.0 -- animatable

Increasing values progressively "cut off" the sphere, starting at the base, to create a partial sphere. Values range from 0.0 to 1.0. The default is 0.0, producing a full sphere. A setting of 0.5 produces a hemisphere, and 1.0 reduces the sphere to nothing.

<Sphere>.chop Integer default: 0

Sets whether the hemisphere is 'chopped' or 'squashed':

0- Chop (Reduces the number of vertices and faces in the sphere by "chopping" them out as the hemisphere is cut off.)

1- Squash (Maintains the number of vertices and faces in the original sphere, "squashing" the geometry into a smaller and smaller volume toward the top of the sphere. Since the geometry is maintained, you can use different versions of a squashed sphere for morph objects.)

<Sphere>.slice Boolean default: false

When on, uses the From and To angles to create a partial sphere. The effect is similar to lathing a semicircular shape fewer than 360 degrees.

<Sphere>.sliceFrom Float default: 0.0 -- animatable, angle, alias: Slice_From

The start angle (on the local Z-axis) for slicing.

<Sphere>.sliceTo Float default: 0.0 -- animatable, angle, alias: Slice_To

The stop angle (on the local Z-axis) for slicing.

<Sphere>.recenter Boolean default: false

When on, moves a sphere upward along its local Z axis so the pivot point is at its base. When off, the pivot point is on the construction plane at the center of the sphere.

<Sphere>.mapCoords Boolean default: false

When on, generates coordinates for applying mapped materials to the box.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Spindle : GeometryClass

Constructor

spindle ...

Properties

<Spindle>.radius Float default: 0.0 -- animatable

The radius of the spindle.

<Spindle>.height Float default: 0.0 -- animatable

The height of the spindle, along the central axis. Negative values create the spindle below the construction plane.

<Spindle>.Cap_Height Float default: 0.0 -- animatable

The height of the conical caps. The minimum value is 0.1; the maximum value is ½ 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.

<Spindle>.Smooth_On Integer default: 1 -- animatable

Turns on/off smooth:

0- off

1- on

<Spindle>.Slice_On Integer default: 0 -- animatable

Turn on/off slice:

0- off

1- on

<Spindle>.Slice_From Float default: 0.0 -- animatable, angle

The start angle (on the local Z-axis) for slicing.

<Spindle>.Slice_To Float default: 0.0 -- animatable, angle

The stop angle (on the local Z-axis) for slicing.

Notes

The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Teapot : GeometryClass

Constructor

teapot ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Teapot>.radius Float default: 25.0 -- animatable

The radius of the teapot.

<Teapot>.segs Integer default: 4 -- animatable, alias: segments

The number of divisions for the teapot or its individual parts.

<Teapot>.smooth Boolean default: true -- animatable

When on, blends faces of the teapot, creating a smooth appearance in rendered views.

<Teapot>.body Boolean default: true -- animatable

When on, the body of the teapot is included in the object.

<Teapot>.handle Boolean default: true -- animatable

When on, the handle of the teapot is included in the object.

<Teapot>.spout Boolean default: true -- animatable

When on, the spout of the teapot is included in the object.

<Teapot>.lid Boolean default: true -- animatable

When on, the lid of the teapot is included in the object.

<Teapot>.mapCoords Boolean default: false

When on, sets up required coordinates for applying mapped materials to the teapot.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Torus : GeometryClass

Constructor

torus ..

Properties

<Torus>.segs Integer default: 24 -- animatable, alias: segments

The number of radial divisions around the torus. By reducing this number, you can create polygonal rings instead of circular ones.

<Torus>.radius1 Float default: 25.0 -- animatable, alias: Radius_1

The distance from the center of the torus to the center of the cross-sectional circle. This is the radius of the torus ring.

<Torus>.radius2 Float default: 10.0 -- animatable, alias: Radius_2

The radius of the cross-sectional circle.

<Torus>.tubeRotation Float default: 0.0 -- animatable, angle

The degree of rotation. Vertices are uniformly rotated about the circle running through the center of the torus ring. Positive and negative values for this setting "roll" the vertices in either direction over the surface of the torus.

<Torus>.tubeTwist Float default: 0.0 -- animatable, angle, alias: Twist

The degree of twist. Cross sections are progressively rotated about the circle running through the center of the torus. Beginning with twist, each successive cross section is rotated until the last one has the number of degrees specified.

<Torus>.sides Integer default: 12 -- animatable

The number of sides on the cross-sectional circle of the torus. By reducing this number, you can create prism-like cross sections instead of circular ones.

<Torus>.smooth Integer default: 0 -- animatable

Select the level of smoothing:

0- None (Turns off smoothing entirely, producing prism-like facets on the torus.)

1- Sides (Smoothes the edges between adjacent segments, producing smooth bands running around the torus.)

2- All (Produces complete smoothing on all surfaces of the torus.)

3- Segments (Smoothes each segment individually, producing ring-like segments along the torus.)

<Torus>.slice Boolean default: false—animatable

When on, creates a portion of a sliced torus rather than the entire 360 degrees.

<Torus>.sliceFrom Float default: 0.0 -- animatable, angle, alias: Slice_From

The angle where the torus slice begins.

<Torus>.sliceTo Float default: 0.0 -- animatable, angle, alias: Slice_To

The angle where the torus slice ends.

<Torus>.mapCoords Boolean default: false

When on, sets up required coordinates for applying mapped materials to the torus.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Torus_Knot: GeometryClass

Constructor

torus_knot ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Torus_Knot>.Base_Curve Integer default: 0

Select the base curve for the Torus Know object:

0- Knot (The torus interweaves itself.)

1- Circle (The base curve is a circle, resulting in a standard torus if parameters are left at their defaults.)

<Torus_Knot>.radius Float default: 0.0 -- animatable

The radius of the base curve.

<Torus_Knot>.segments Integer default: 120 -- animatable

The number of segments around the perimeter of the torus.

<Torus_Knot>.p Float default: 2.0 -- animatable

Describe up and around-the-center winding numbers.

<Torus_Knot>.q Float default: 3.0 -- animatable

Describe down and around-the-center winding numbers.

<Torus_Knot>.Warp_Count Float default: 0.0 -- animatable

The number of "points" in a star shape around the curve.

<Torus_Knot>.Warp_Height Float default: 0.0 -- animatable

The height of the "points" given as a percentage of the base curve radius.

<Torus_Knot>.radius2 Float default: 10.0 -- animatable

The radius of the cross section of the torus knot object.

<Torus_Knot>.sides Integer default: 12 -- animatable

The number of sides around the cross section.

<Torus_Knot>.Eccentricity Float default: 1.0 -- animatable

The ratio of the major to minor axes of the cross section. A value of 1 provides a circular cross section, while other values create elliptical cross sections.

<Torus_Knot>.Twist Float default: 0.0 -- animatable

The number of times the cross section twists around the base curve.

<Torus_Knot>.Lumps Float default: 0.0 -- animatable

The number of bulges in the torus knot.

<Torus_Knot>.Lump_Height Float default: 0.0 -- animatable

The height of the lumps, as a percentage of the radius of the cross section.

<Torus_Knot>.Lump_Offset Float default: 0.0 -- animatable, angle

The offset of the start of the lumps, measured in degrees. The purpose of this value is to animate the lumps around the torus.

<Torus_Knot>.smooth Integer default: 2

Set smoothing in the torus knot:

0- None (The torus knot is faceted.)

1- Sides (Smoothes only the adjacent sides of the torus knot.)

2- All (The torus knot is faceted.)

<Torus_Knot>.Gen_UV Integer default: 0

Turn on/off generate mapping coordinates

0- Off

1- On

<Torus_Knot>.U_Tile Float default: 1.0 -- animatable

Tile the mapping coordinates along U.

<Torus_Knot>.V_Tile Float default: 1.0 -- animatable

Tile the mapping coordinates along V.

<Torus_Knot>.U_Offset Float default: 0.0 -- animatable

Offset the mapping coordinates along U.

<Torus_Knot>.V_Offset Float default: 0.0 -- animatable

Offset the mapping coordinates along V.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Tube : GeometryClass

Constructor

tube ...

Properties

<Tube>.radius1 Float default: 25.0 -- animatable, alias: Radius_1

The first radius for the tube.

<Tube>.radius2 Float default: 20.0 -- animatable, alias: Radius_2

The second radius for the tube.

Note: The larger radius specifies the outside radius of the tube, while the smaller specifies the inside radius.

<Tube>.height Float default: 50.0 -- animatable

The dimension along the central axis. Negative values create the tube below the construction plane.

<Tube>.heightsegs Integer default: 1 -- animatable, alias: Height_Segments

The number of divisions along the tube's major axis.

<Tube>.capsegs Integer default: 1 -- animatable, alias: Cap_Segments

The number of concentric divisions around the center of the tube's top and bottom.

<Tube>.sides Integer default: 24 -- animatable

The number of sides around the tube. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off.

<Tube>.smooth Boolean default: true -- animatable

When on, faces of the tube are blended together, creating a smooth appearance in rendered views.

<Tube>.slice Boolean default: false—animatable

Enables/Disables the Slice feature, which removes part of the tube's circumference.

<Tube>.Slice_On Integer default: 0

Integer alias of slice:

0- off

1- on

<Tube>.sliceFrom Float default: 0.0 -- animatable, angle, alias: Slice_From

The angle where the tube slice begins.

<Tube>.sliceTo Float default: 0.0 -- animatable, angle, alias: Slice_To

The angle where the tube slice ends.

<Tube>.mapCoords Boolean default: false

When on, sets up required coordinates for applying mapped materials to the tube.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Geometry - Dynamics Objects

The following list displays the dynamics objects:

Damper

Spring


Damper : GeometryClass

Constructor

damper ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Damper>.End_Placement_Method Integer default: 1

Set binding method for damper:

0- Reference Objects (Choose this option when binding the damper to two objects.)

1- Free Spring (Choose this when using the damper as a simple object that's not bound to others or used in a dynamics simulation.)

<Damper>.Free_Damper_Height Float default: 2.0 -- animatable

The distance between the bottom center of the base and the top center of the piston when the damper is not bound.

<Damper>.Renderable_Spring Integer default: 1

Turn on/off renderability of the damper:

0- not renderable

1- renderable

<Damper>.Generate_Mapping_Coordinates Integer default: 0

Turn on/off mapping coordinates for the object:

0- off

1- on

<Damper>.Base_Stud_Diameter Float default: 0.5 -- animatable

The diameter of the base, or "mount" of the damper.

<Damper>.Base_Stud_Height Float default: 0.2 -- animatable

The height of the base.

<Damper>.Cylinder_Diameter Float default: 1.0 -- animatable

The diameter of the main housing of the damper.

<Damper>.Cylinder_Height Float default: 1.0 -- animatable

The height of the main housing.

<Damper>.Cylinder_Sides Integer default: 8 -- animatable

The number of sides of both the base and the main housing.

<Damper>.Cylinder_Fillet_1 Float default: 0.0 -- animatable

The size of the fillet on the lower edge of the main housing.

<Damper>.Cylinder_Fillet_1_Segments Integer default: 0 -- animatable

The number of segments for Fillet 1. The higher this setting, the rounder the fillet profile appears.

<Damper>.Cylinder_Fillet_2 Float default: 0.0 -- animatable

The size of the fillet on the upper edge of the main housing.

<Damper>.Cylinder_Fillet_2_Segments Integer default: 0 -- animatable

The number of segments for Fillet 2. The higher this setting, the rounder the fillet profile appears.

<Damper>.Inside_Diameter Float default: 0.0 -- animatable

The inside diameter of the main housing, which is actually a tube rather than a cylinder.

<Damper>.Smooth_Cylinder Integer default: 1

Turn on/off smoothing for the base and the main housing:

0- Off

1- On

<Damper>.Piston_Diameter Float default: 0.2 -- animatable

The diameter of the piston.

<Damper>.Piston_Height Float default: 1.0 -- animatable

The height of the piston.

<Damper>.Piston_Sides Integer default: 6 -- animatable

The number of sides in the piston.

<Damper>.Smooth_Piston Integer default: 1

Turn on/off smoothing for the piston:

0- Off

1- On

<Damper>.Enable_Boot Integer default: 0

Turn this on to add the boot to the damper:

0- Off

1- On

The boot is an optional component of the damper that's similar to the rubber "accordion" boot found on various types of dampers, such as shock absorbers. The boot acts like a bound dynamic object, in that one of its ends is bound to the main housing, while the other is bound to the piston. Thus, as the piston moves within the housing, the boot expands and contracts to follow.

<Damper>.Boot_Small_Diameter Float default: 0.25 -- animatable

The minimum diameter of the boot. This and the next parameter affect the depth of the accordion folds in the boot.

<Damper>.Boot_Large_Diameter Float default: 1.0 -- animatable

The maximum diameter of the boot.

<Damper>.Boot_Sides Integer default: 8 -- animatable

The number of sides making up the boot.

<Damper>.Boot_Folds Integer default: 4 -- animatable

The number of accordion folds (bulges) along the height of the boot.

<Damper>.Boot_Fold_Resolution Integer default: 4 -- animatable

The number of segments in each fold.

<Damper>.Boot_Stop_Diameter Float default: 0.4 -- animatable

The diameter of the stop, which is the ring at the top of the boot.

<Damper>.Boot_Stop_Height Float default: 0.2 -- animatable

The thickness (height) of the stop ring.

<Damper>.Boot_Stop_Setback Float default: 0.2 -- animatable

The distance of the stop ring from the top of the piston.

<Damper>.Boot_Stop_Fillet Float default: 0.0 -- animatable

The size of the fillet on the upper edge of the stop ring.

<Damper>.Boot_Stop_Fillet_Segements Integer default: 0 -- animatable

The number of segments the stop fillet. The higher this setting, the round the fillet profile appears.

<Damper>.Smooth_Boot Integer default: 1

Turn on/off smoothing for the boot:

0- Off

1- On

<Damper>.Dynamics_Object_Type Integer default: 0

Select which object is dynamic:

0- Damper (Select this option to use the damper object as a damper rather than an actuator.)

1- Actuator (Choose this when using the damper object as an Actuator.)

<Damper>.Drag Float default: 0.0 -- animatable

The force per unit linear speed.

<Damper>.Drag_Units Integer default: 0

Sets the units of drag:

0- Pounds per inch/second

1- Newtons per meter/second

<Damper>.Damper_Direction Integer default: 2

Set the directional operation of the damper:

0- Compression Only (The damper reacts only to compression forces.)

1- Extension Only (The damper reacts only to expansion forces.)

2- Both (The damper reacts to both compression and expansion forces.)

<Damper>.Force Float default: 0.0 -- animatable

The amount of force exerted between the two bound objects. Positive values push the objects apart, while negative values pull them together.

<Damper>.Force_Units Integer default: 0

Set the units of force:

0- Pounds

1- Newtons

Notes

The Reference End Point objects cannot be specified in MAXScript in 3ds max R4.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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:

0- Reference Objects (Choose this when binding the spring to two objects.)

1- Free Spring (Choose this when using the spring as a simple object that's not bound to other objects or used in a dynamics simulation.)

<Spring>.Free_Spring_Height Float default: 1.0 -- animatable

The straight-line height or length of the spring when it is not bound. This is not the actual length of the spring's wire.

<Spring>.Diameter Float default: 1.0 -- animatable

The overall diameter of the spring, as measured at the center of the wire. (The diameter of the wire itself has no effect on this setting.)

<Spring>.Number_of_Turns Float default: 1.0 -- animatable

The number of full 360-degree turns in the spring.

<Spring>.Turn_Direction Integer default: 0

Sets the direction of the turns in the spring:

0- counterclockwise

1- clockwise

<Spring>.Segmentation_Method Integer default: 0

Sets the segmentation method of the springs:

0- 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.)

1- 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:

0- All (All surfaces are smoothed.)

1- None (No smoothing is applied.)

2- Sides (Smoothing runs along the length of the wire, but not around its perimeter.)

3- Segments (Smoothing runs around the perimeter of the wire, but not along its length.)

<Damper>.Renderable_Spring Integer default: 1

When on, the object appears in the rendering; when off, the object does not appear:

0- Not renderable

1- Renderable

<Spring>.Wire Integer default: 0 -- animatable

Set the shape of the wire:

0- Round

1- Rectangular

2- D-Section

<Spring>.Generate_Mapping_Coordinates Integer default: 0

Turn on/off generate texture coordinates

0- Off

1- On

<Spring>.Round_Wire_Diameter Float default: 0.2 -- animatable

The diameter of the wire.

<Spring>.Round_Wire_Side_Count Integer default: 6 -- animatable

The number of sides that make up the cross section of the round wire.

<Spring>.Rectangular_Wire_Width Float default: 0.2 -- animatable

Determines the width of the rectangular cross section.

<Spring>.Rectangular_Wire_Depth Float default: 0.2 -- animatable

Determines the depth of the rectangular cross section.

<Spring>.Rectangular_Wire_Fillet_Size Float default: 0.0 -- animatable

When combined with .Rectangular_Fillet_Sides, this lets you fillet (round) the corners of the cross section.

<Spring>.Rectangular_Fillet_Sides Integer default: 0 -- animatable

The number of segments in the fillet.

<Spring>.Rectangular_Wire_Rotation_Angle Float default: 0.0 -- animatable, angle

Rotates the angle of the cross section along the entire length of the spring.

<Spring>.D_Section_Wire_Width Float default: 0.2 -- animatable

Determines the width of the cross section.

<Spring>.D_Section_Wire_Depth Float default: 0.2 -- animatable

Determines the depth of the cross section.

<Spring>.D_Section_Round_Sides Integer default: 4 -- animatable

The number of segments that make up the rounded side of the D-shape.

<Spring>.D_Section_Wire_Fillet_Size Float default: 0.0 -- animatable

When combined with .D_Section_Wire_Fillet_Sides, this lets you fillet (round) the corners of the cross section.

<Spring>.D_Section_Wire_Fillet_Sides Integer default: 0 -- animatable

The number of segments in the fillet.

<Spring>.D_Section_Wire_Rotation_Angle Float default: 0.0 -- animatable, angle

Rotates the angle of the cross section along the entire length of the spring.

<Spring>.Dynamics_Spring_Free_Height Float default: 1.0 -- animatable

Specifies the height (or length) at which the spring is "relaxed" and therefore contributes no force—either compression or extension.

<Spring>.Dynamics_K_Constant_Value Float default: 1.0 -- animatable

The amount of force exerted per unit change in length with respect to the Relaxed Hgt value. This could also be described as the measure of force-per-units-change in length as compared to the Relaxed Length.

<Spring>.Dynamics_K_Constant_Units Integer default: 0

Sets the Units for the K constant:

0- Pounds per inch

1- Newtons per meter

<Spring>.Dynamics_Spring_Direction Integer default: 0

Lets you specify the type of force you want the spring to exert. While most springs actually provide both compression and extension force, if your simulation requires only one, you can save calculation time by using one instead of both.

0- Compression Only (This type of spring provides only expansive force when its length is shorter than the specified Free Length.)

1- Extension Only (Provides contractive force when its length is greater than the specified Free Length.)

2- 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:

0- Off

1- On

Notes

The Reference End Point objects cannot be specified in MAXScript in 3ds max R4.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Geometry - Compound Objects

The following list displays the compound objects:

OldBoolean

Boolean2

Conform

Connect

Loft

Morph

Scatter

ShapeMerge

Terrain


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 Boolean2 for a constructable boolean object.


Boolean2 : GeometryClass

Constructor

boolObj.createBooleanObject <operand_A> [ <operand_B> <add_method> <mat_method> ]

Creates a Boolean2 object using node <operand_A> and an optional node <operand_B>. <add_method> specifies how <operand_B> is to be used as follows:

1 - instance, operand is an instance of the original node

2 - reference, operand is a reference to original node

3 - copy, operand is a copy of original node

4 - move, original node should be deleted

<mat_method> specifies how the materials of the two operands are to be handled as follows:

1 - combines materials without changing them or the ID's

2 - matches ID's to materials, then combines materials

3 - matches materials to ID's, then combines them

4 - discards original material, uses new node's instead

5 - discards new node's material, uses original

Properties

The following properties are available only after the boolean2 object has been created. The values shown for the properties are those for a boolean2 object created from two spheres. The operand transforms are in the local coordinate system of the boolean2 object.

<bool_obj>.Sphere02 SubAnim default: SubAnim:Sphere02

<bool_obj>.Operand_A_Transform SubAnim default: SubAnim:Operand_A_Transform

<bool_obj>.Sphere01 SubAnim default: SubAnim:Sphere01

<bool_obj>.Operand_B_Transform SubAnim default: SubAnim:Operand_B_Transform

Methods

boolObj.setOperandB <bool_obj> <operand_B> <add_method> <mat_method>

sets operand B. The values for <add_method> and <mat_method> are describe above.

boolObj.getOperandSel <bool_obj> <integer>

boolObj.setOperandSel <bool_obj> <integer> <boolean>

these methods get and set whether operand_A and operand_B are selected in the Operands list. <integer> = 1 - operand_A, 2 - operand_B

boolObj.getBoolOp <bool_obj>

boolObj.setBoolOp <bool_obj> <integer>

these methods get and set the boolean Operation Type. Valid values are:

1 - Union

2 - Intersection

3 - Subtraction (A-B)

4 - Subtraction (B-A)

5 - Cut

boolObj.getBoolCutType <bool_obj>

boolObj.setBoolCutType <bool_obj> <integer>

these methods get and set the boolean Cut Type. The value for this property only has an effect if the Operation Type is Cut. The Cut Types are:

1 - Refine

2 - Split

3 - Remove Inside

4 - Remove Outside

boolObj.getDisplayResult <bool_obj>

boolObj.setDisplayResult <bool_obj> <boolean>

these methods get and set whether Results or Operands are displayed. If true, Result is displayed. If false, Operands are displayed.

boolObj.getShowHiddenOps <bool_obj>

boolObj.setShowHiddenOps <bool_obj> <boolean>

these methods get and set whether Results + Hidden Operands are displayed. If true, Results + Hidden Operands are displayed. If false, the Results or Operands as specified using boolObj.SetDisplayResult() are displayed.

boolObj.getUpdateMode <bool_obj>

boolObj.setUpdateMode <bool_obj> <integer>

these methods get and set the Update mode as follows:

1 - Always

2 - When Rendering

3 - Manually

boolObj.getOptimize <bool_obj>

boolObj.setOptimize <bool_obj> <boolean>

these methods get and set whether vertices are to be welded on the boolean result

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Conform : GeometryClass

Constructor

Conform compound objects are not constructable by MAXScript in 3ds max 4.

Properties

<Conform>.Projection_Distance Float default: 1.0 -- animatable

The distance a vertex in the Wrapper object will move from its original location if it does not intersect the Wrap-To object.

<Conform>.Standoff_Distance Float default: 1.0 -- animatable

The distance maintained between the vertex of the Wrapper object and the surface of the Wrap-To object

The following properties are available only after the conform object has been created. The values shown for the properties are those for a conform object created from two spheres. The operand transforms are in the local coordinate system of the conform object.

<Conform>.S_Sphere02 SubAnim default: SubAnim:S_Sphere02

<Conform>.Operand_A_Transform SubAnim default: SubAnim:Operand_A_Transform

<Conform>.D_Sphere01 SubAnim default: SubAnim:D_Sphere01

<Conform>.Operand_B_Transform SubAnim default: SubAnim:Operand_B_Transform

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Connect : GeometryClass

Constructor

Connect compound objects are not constructable by MAXScript in 3ds max 4.

Properties

<Connect>.segments Integer default: 0 -- animatable

The number of segments in the connecting bridge.

<Connect>.tension Float default: 0.5 -- animatable

Controls the curvature in the connecting bridge. A value of 0 provides no curvature, while higher values create curves that attempt to more smoothly match the surface normals on either end of the connecting bridge.

The following properties are available only after the connect object has been created. The values shown for the properties are those for a connect object created from two spheres. Similar SubAnims would be created if additions operands were used. The operand transforms are in the local coordinate system of the connect object.

<Connect>.Op_0__Sphere02 SubAnim default: SubAnim:Op_0__Sphere02

<Connect>.Op_0_Transform SubAnim default: SubAnim:Op_0_Transform

<Connect>.Op_1__Sphere01 SubAnim default: SubAnim:Op_1__Sphere01

<Connect>.Op_1_Transform SubAnim default: SubAnim:Op_1_Transform

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Loft : GeometryClass

Constructor

Loft compound objects are not constructable by MAXScript in 3ds max 4.

Properties

<Loft>.Def_Scale_X SubAnim default: SubAnim:Def_Scale_X

<Loft>.Def_Scale_Y SubAnim default: SubAnim:Def_Scale_Y

<Loft>.Def_Twist SubAnim default: SubAnim:Def_Twist

<Loft>.Def_Teeter_X SubAnim default: SubAnim:Def_Teeter_X

<Loft>.Def_Teeter_Y SubAnim default: SubAnim:Def_Teeter_Y

<Loft>.Def_Bevel SubAnim default: SubAnim:Def_Bevel

<Loft>.Def_Fit_X SubAnim default: SubAnim:Def_Fit_X

<Loft>.Def_Fit_Y SubAnim default: SubAnim:Def_Fit_Y

These SubAnims contain the deformation curves of the loft object. You cannot create or access points in these curves unless the point is animated. In this case, you can access the animated point position as a SubAnim of the property.

The following properties are available only after the loft object has been created. The values shown for the properties are those for a loft object created from an ellipse (the path) and a circle (the shape).

<loft>.ellipse SubAnim default: SubAnim:Ellipse

<Loft>.circle SubAnim default: SubAnim:Circle

These SubAnims contain the parameters of the path and shape objects, respectively. If multiple shapes are used in a loft, each of these shape objects will have a corresponding SubAnim.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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 MorphController for a description of these methods.

Properties

The following properties are available only after the morph object has been created. The values shown for the properties are those for a morph object created from three spheres.

<Morph>.M_Sphere01 SubAnim default: SubAnim:M_Sphere01

<Morph>.M_Sphere02 SubAnim default: SubAnim:M_Sphere02

<Morph>.M_Sphere03 SubAnim default: SubAnim:M_Sphere03

<Morph>.Morph Barycentric_Morph_Controller default: Controller:Barycentric_Morph_Controller

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Scatter : GeometryClass

Constructor

Scatter compounds are not constructable by MAXScript in 3ds max 4.

Properties

<Scatter>.Duplicates Integer default: 1 -- animatable

The number of scattered duplicates of the source object.

<Scatter>.Base_Scale Float default: 100.0 -- animatable, percentage

Alters the scale of the source object, affecting each duplicate identically. This scale occurs before any other transforms.

<Scatter>.Vertex_Chaos Float default: 0.0 -- animatable

Applies a random perturbation to the vertices of the source object.

<Scatter>.Animation_Offset Time default: 0f -- animatable

The number of frames by which each source object duplicate's animation is offset from the previous duplicate.

<Scatter>.x_rotation Float default: 0.0 -- animatable

The maximum random rotational offset you want about the local X-axis of each duplicate.

<Scatter>.y_rotation Float default: 0.0 -- animatable

The maximum random rotational offset you want about the local Y-axis of each duplicate.

<Scatter>.z_rotation Float default: 0.0 -- animatable

The maximum random rotational offset you want about the local Z-axis of each duplicate.

<Scatter>.X_Translation Float default: 0.0 -- animatable

The maximum random movement you want along the X-axis of each duplicate.

<Scatter>.Y_Translation Float default: 0.0 -- animatable

The maximum random movement you want along the Y-axis of each duplicate.

<Scatter>.Z_Translation Float default: 0.0 -- animatable

The maximum random movement you want along the Z-axis of each duplicate.

<Scatter>.A_Translation_on_Face Float default: 0.0 -- animatable

The first barycentric coordinate on the surface of the face, upon which duplicates are translated.

<Scatter>.B_Translation_on_Face Float default: 0.0 -- animatable

The second barycentric coordinate on the surface of the face, upon which duplicates are translated.

<Scatter>.N_Translation_on_Face Float default: 0.0 -- animatable

The offset along the normal of the face, upon which duplicates are translated.

<Scatter>.Local_X_Scaling Float default: 0.0 -- animatable

The percent of random scaling along the X-axis of each duplicate.

<Scatter>.Local_Y_Scaling Float default: 0.0 -- animatable

The percent of random scaling along the X-axis of each duplicate.

<Scatter>.Local_Z_Scaling Float default: 0.0 -- animatable

The percent of random scaling along the X-axis of each duplicate.

The following properties are available only after the Scatter object has been created. The values shown for the properties are those for a Scatter object created from two boxes. The operand transforms are in the local coordinate system of the Scatter object.

<Scatter>.S_Box04 SubAnim default: SubAnim:S_Box04

<Scatter>.Operand_A_Transform SubAnim default: SubAnim:Operand_A_Transform

<Scatter>.D_Box05 SubAnim default: SubAnim:D_Box05

<Scatter>.Operand_B_Transform SubAnim default: SubAnim:Operand_B_Transform

Notes

Many properties associated with Scatter are not accessible to MAXScript in 3ds max 4.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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:

0- Cookie Cutter (Cuts the shape out of the mesh object's surface.)

1- Merge (Merges the shape with the surface of the mesh object.)

<ShapeMerge>.Remove_Interior_Exterior Integer default: 0

Reverses the effect of Cookie Cutter or Merge. With the Cookie Cutter option, the effect is obvious. When Invert is off, the shape is a hole in the mesh object. When Invert is on, the shape is solid and the mesh is missing. When you're using Merge, Invert reverses the sub-object mesh selection.

0- Invert OFF

1- Invert ON

<ShapeMerge>.Output_Sub_Mesh_Selection Integer default: 0

Sets which selection level is output:

0- None (Outputs the full object.)

1- Vertex (Outputs the vertices defined by the spline of the shape.)

2- Edge (Outputs the edge of the merged shape.)

3- Face (Outputs the faces within the merged shape.)

The following properties are available only after the ShapeMerge object has been created. The values shown for the properties are those for a ShapeMerge object created from a sphere and a circle. SubAnims similar to the Circle01 SubAnim would be created if additions operands were used. The operand transforms are in the local coordinate system of the ShapeMerge object.

<ShapeMerge>.mesh__sphere01 SubAnim default: SubAnim:Mesh__Sphere01

<ShapeMerge>.mesh_transform SubAnim default: SubAnim:Mesh_Transform

<ShapeMerge>.shape_1__circle01 SubAnim default: SubAnim:Shape_1__Circle01

<ShapeMerge>.shape_1_transform SubAnim default: SubAnim:Shape_1_Transform

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Terrain : GeometryClass

Constructor

Terrain()

Properties

<Terrain>.Form Integer default: 1

Set the terrain form:

0- Graded Surface (Creates a graded surface of the mesh over the contours.)

1- 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.)

2- Layered Solid (Creates a "wedding cake" or laminated solid similar to cardboard architectural models.)

<Terrain>.stitchBorder Boolean default: false

Turn on/off stitch border.

<Terrain>.retriangulate Boolean default: false

Turn on/off retriangulate.

<Terrain>.display Integer default: 0

Select the type of display for the terrain object:

0- Terrain (Displays only the triangulated mesh over the contour line data.)

1- Contours (Displays only the contour line data of the terrain object.)

2- Both (Displays both the triangulated mesh and the contour line data of the terrain object.)

<Terrain>.update Integer default: 0

Set update settings for the terrain object:

0- Always (Updates the terrain object immediately when you change an operand, including the original object of an instanced or referenced operand.)

1- 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.)

2- Manually (Updates the terrain object when you force an update.)

Note: The following properties of terrain compound objects cannot be operated on with MAXScript in 3ds max R4. However, they can be used by MAXScript in 3D Studio VIZ.

<Terrain>.numOps Integer default: 0

The number of contour operands. Read-only.

<Terrain>.horizSimplification Integer default: 0

horizSimplification = 0 – No Simplification; 1 – Use ½ of Points; 2 - Use ¼ of Points; 3 – Interpolate Points * 2; 4 - Interpolate Points * 4

<Terrain>.vertSimplification Integer default: 0

vertSimplification = 0 - No Simplification; Use ½ of Lines; 2 - Use ¼ of Lines

The following properties are available only after the terrain object has been created. The values shown for the properties are those for a terrain object created from three circles. The operand transforms are in the local coordinate system of the terrain object.

<Terrain>.Op_0__Circle01 SubAnim default: SubAnim:Op_0__Circle01

<Terrain>.Op_0_Transform SubAnim default: SubAnim:Op_0_Transform

<Terrain>.Op_1__Circle02 SubAnim default: SubAnim:Op_1__Circle02

<Terrain>.Op_1_Transform SubAnim default: SubAnim:Op_1_Transform

<Terrain>.Op_2__Circle03 SubAnim default: SubAnim:Op_2__Circle03

<Terrain>.Op_2_Transform SubAnim default: SubAnim:Op_2_Transform

Notes

All properties other than Form are not accessible in 3ds max.

Methods

The following methods are available in 3DS VIZ:

terrainOps.addOperand <terrain> <node>

Appends a node as a contour operand to the terrain. Note this is done in 'Move' mode, so the the supplied node is deleted after the addition. To simulate other modes, use appropriate MAXScript functions. For example,

terrainOps.addOperand $terrain01 (instance $line03)

terrainOps.deleteOperand <terrain> <index_integer>

Deletes the indexed operand, index_integer is 1-based.

terrainOps.getOperand <terrain> <index_integer>

Returns the indexed contour operand as a 3ds max base object (not a node), index_integer is 1-based.

terrainOps.getOperandTM <terrain> <index_integer>

Returns the indexed operand's local transformation matrix as a Matrix3 value. This transformation matrix is relative to the terrain's node transformation matrix.

terrainOps.setOperandTM <terrain> <index_integer> <matrix3>

Sets the indexed operand's local transformation matrix. This transformation matrix is relative to the terrain's node transformation matrix.

terrainOps.update <terrain>

Forces a terrain update for those in manual update mode.

Notes

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

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Geometry - Doors and Windows

The following list displays the door and window objects:

Awning

BiFold

Casement

Fixed

Pivot

Pivoted

Projected

SlidingDoor

SlidingWindow


Awning : GeometryClass

Constructor

awning ...

Properties

<Awning>.height Float default: 0.0 -- animatable

<Awning>.width Float default: 0.0 -- animatable

<Awning>.depth Float default: 0.0 -- animatable

<Awning>.Horizontal_Frame_Width Float default: 2.0 -- animatable

<Awning>.Vertical_Frame_Width Float default: 2.0 -- animatable

<Awning>.Frame_Thickness Float default: 0.5 -- animatable

<Awning>.Glazing_Thickness Float default: 0.25 -- animatable

<Awning>.Rail_Width Float default: 1.0 -- animatable

<Awning>.Number_of_Panels Integer default: 1

<Awning>.Percent_Open Integer default: 0 -- animatable

<Awning>.Generate_Mapping_Coords Boolean default: false

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


BiFold : GeometryClass

Constructor

bifold ...

Properties

<BiFold>.height Float default: 0.0 -- animatable

<BiFold>.width Float default: 0.0 -- animatable

<BiFold>.depth Float default: 0.0 -- animatable

<BiFold>.Double_Doors Integer default: 0

Double_Doors = 0 - false; 1 - true

<BiFold>.Flip_Swing Boolean default: false

<BiFold>.Flip_Hinge Boolean default: false

<BiFold>.open Float default: 0.0 -- animatable

<BiFold>.Create_Frame Boolean default: true

<BiFold>.Frame_Width Float default: 2.0 -- animatable

<BiFold>.Frame_Depth Float default: 1.0 -- animatable

<BiFold>.Door_Offset Float default: 0.0 -- animatable

<BiFold>.Generate_Mapping_Coords Boolean default: false

<BiFold>.Leaf_Thickness Float default: 2.0 -- animatable

<BiFold>.Stiles_Top_Rail Float default: 4.0 -- animatable

<BiFold>.Bottom_Rail Float default: 12.0 -- animatable

<BiFold>.Number_of_Panels_Horizontally Integer default: 1

<BiFold>.Number_of_Panels_Vertically Integer default: 1

<BiFold>.Muntin Float default: 2.0 -- animatable

<BiFold>.Panel_Type Integer default: 1

Panel_Type = 0 - None; 1 - Glass; 2 - Beveled

<BiFold>.Glass_Thickness Float default: 0.25 -- animatable

<BiFold>.Bevel_Angle Float default: 45.0 -- animatable

<BiFold>.Panel_Thickness_1 Float default: 0.25 -- animatable

<BiFold>.Panel_Thickness_2 Float default: 0.5 -- animatable

<BiFold>.Panel_Middle_Thickness Float default: 0.25 -- animatable

<BiFold>.Panel_Width_1 Float default: 1.0 -- animatable

<BiFold>.Panel_Width_2 Float default: 0.5 -- animatable

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Casement : GeometryClass

Constructor

casement ...

Properties

<Casement>.height Float default: 0.0 -- animatable

<Casement>.width Float default: 0.0 -- animatable

<Casement>.depth Float default: 0.0 -- animatable

<Casement>.Horizontal_Frame_Width Float default: 2.0 -- animatable

<Casement>.Vertical_Frame_Width Float default: 2.0 -- animatable

<Casement>.Frame_Thickness Float default: 0.5 -- animatable

<Casement>.Glazing_Thickness Float default: 0.25 -- animatable

<Casement>.Panel_Width Float default: 1.0 -- animatable

<Casement>.Number_of_Casements Integer default: 1

Number_of_Casements = 1 - One; 2 - Two

<Casement>.Percent_Open Integer default: 0 -- animatable

<Casement>.Opens_to_Inside Boolean default: false

<Casement>.Generate_Mapping_Coords Boolean default: false

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Fixed : GeometryClass

Constructor

fixed ...

Properties

<Fixed>.height Float default: 0.0 -- animatable

<Fixed>.width Float default: 0.0 -- animatable

<Fixed>.depth Float default: 0.0 -- animatable

<Fixed>.Horizontal_Frame_Width Float default: 2.0 -- animatable

<Fixed>.Vertical_Frame_Width Float default: 2.0 -- animatable

<Fixed>.Frame_Thickness Float default: 0.5 -- animatable

<Fixed>.Glazing_Thickness Float default: 0.25 -- animatable

<Fixed>.Rail_Width Float default: 1.0 -- animatable

<Fixed>.Number_of_Panels_Horizontally Integer default: 1

<Fixed>.Number_of_Panels_Vertically Integer default: 1

<Fixed>.Chamfered_Profile Boolean default: false

<Fixed>.Generate_Mapping_Coords Boolean default: false

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Pivot : GeometryClass

Constructor

pivot ...

Properties

<pivot>.height Float default: 0.0 -- animatable

<pivot>.width Float default: 0.0 -- animatable

<pivot>.depth Float default: 0.0 -- animatable

<pivot>.Double_Doors Integer default: 0

Double_Doors = 0 - false; 1 - true

<pivot>.Flip_Swing Boolean default: false

<pivot>.Flip_Hinge Boolean default: false

<pivot>.Open__degrees Float default: 0.0 -- animatable

<pivot>.Create_Frame Boolean default: true

<pivot>.Frame_Width Float default: 2.0 -- animatable

<pivot>.Frame_Depth Float default: 1.0 -- animatable

<pivot>.Door_Offset Float default: 0.0 -- animatable

<pivot>.Generate_Mapping_Coords Boolean default: false

<pivot>.Leaf_Thickness Float default: 2.0 -- animatable

<pivot>.Stiles_Top_Rail Float default: 4.0 -- animatable

<pivot>.Bottom_Rail Float default: 12.0 -- animatable

<pivot>.Number_of_Panels_Horizontally Integer default: 1

<pivot>.Number_of_Panels_Vertically Integer default: 1

<pivot>.Muntin Float default: 2.0 -- animatable

<pivot>.Panel_Type Integer default: 1

Panel_Type = 0 - None; 1 - Glass; 2 - Beveled

<pivot>.Glass_Thickness Float default: 0.25 -- animatable

<pivot>.Bevel_Angle Float default: 45.0 -- animatable

<pivot>.Panel_Thickness_1 Float default: 0.25 -- animatable

<pivot>.Panel_Thickness_2 Float default: 0.5 -- animatable

<pivot>.Panel_Middle_Thickness Float default: 0.25 -- animatable

<pivot>.Panel_Width_1 Float default: 1.0 -- animatable

<pivot>.Panel_Width_2 Float default: 0.5 -- animatable

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Pivoted : GeometryClass

Constructor

pivoted ...

Properties

<Pivoted>.height Float default: 0.0 -- animatable

<Pivoted>.width Float default: 0.0 -- animatable

<Pivoted>.depth Float default: 0.0 -- animatable

<Pivoted>.Horizontal_Frame_Width Float default: 2.0 -- animatable

<Pivoted>.Vertical_Frame_Width Float default: 2.0 -- animatable

<Pivoted>.Frame_Thickness Float default: 0.5 -- animatable

<Pivoted>.Glazing_Thickness Float default: 0.25 -- animatable

<Pivoted>.Rail_Width Float default: 1.0 -- animatable

<Pivoted>.Vertical_Rotation Boolean default: false

<Pivoted>.Percent_Open Integer default: 0 -- animatable

<Pivoted>.Generate_Mapping_Coords Boolean default: false

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Projected : GeometryClass

Constructor

projected ...

Properties

<projected>.height Float default: 0.0 -- animatable

<projected>.width Float default: 0.0 -- animatable

<projected>.depth Float default: 0.0 -- animatable

<projected>.Horizontal_Frame_Width Float default: 2.0 -- animatable

<projected>.Vertical_Frame_Width Float default: 2.0 -- animatable

<projected>.Frame_Thickness Float default: 0.5 -- animatable

<projected>.Glazing_Thickness Float default: 0.25 -- animatable

<projected>.Rail_Width Float default: 1.0 -- animatable

<projected>.Middle_Height Float default: 0.0 -- animatable

<projected>.Bottom_Height Float default: 0.0 -- animatable

<projected>.Percent_Open Integer default: 0 -- animatable

<projected>.Generate_Mapping_Coords Boolean default: false

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SlidingDoor : GeometryClass

Constructor

slidingDoor ...

Properties

<SlidingDoor>.height Float default: 0.0 -- animatable

<SlidingDoor>.width Float default: 0.0 -- animatable

<SlidingDoor>.depth Float default: 0.0 -- animatable

<SlidingDoor>.Flip_Swing Boolean default: false

<SlidingDoor>.Flip_Hinge Boolean default: false

<SlidingDoor>.open Float default: 0.0 -- animatable

<SlidingDoor>.Create_Frame Boolean default: true

<SlidingDoor>.Frame_Width Float default: 2.0 -- animatable

<SlidingDoor>.Frame_Depth Float default: 1.0 -- animatable

<SlidingDoor>.Door_Offset Float default: 0.0 -- animatable

<SlidingDoor>.Generate_Mapping_Coords Boolean default: false

<SlidingDoor>.Leaf_Thickness Float default: 2.0 -- animatable

<SlidingDoor>.Stiles_Top_Rail Float default: 4.0 -- animatable

<SlidingDoor>.Bottom_Rail Float default: 12.0 -- animatable

<SlidingDoor>.Number_of_Panels_Horizontally Integer default: 1

<SlidingDoor>.Number_of_Panels_Vertically Integer default: 1

<SlidingDoor>.Muntin Float default: 4.0 -- animatable

<SlidingDoor>.Panel_Type Integer default: 1

Panel_Type = 0 - None; 1 - Glass; 2 - Beveled

<SlidingDoor>.Glass_Thickness Float default: 0.25 -- animatable

<SlidingDoor>.Bevel_Angle Float default: 45.0 -- animatable

<SlidingDoor>.Panel_Thickness_1 Float default: 0.25 -- animatable

<SlidingDoor>.Panel_Thickness_2 Float default: 0.5 -- animatable

<SlidingDoor>.Panel_Middle_Thickness Float default: 0.25 -- animatable

<SlidingDoor>.Panel_Width_1 Float default: 1.0 -- animatable

<SlidingDoor>.Panel_Width_2 Float default: 0.5 -- animatable

<SlidingDoor>.Double_Doors Integer default: 0

Notes

The Double_Doors property is not used by SlidingDoor.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SlidingWindow : GeometryClass

Constructor

slidingWindow ...

Properties

<SlidingWindow>.height Float default: 0.0 -- animatable

<SlidingWindow>.width Float default: 0.0 -- animatable

<SlidingWindow>.depth Float default: 0.0 -- animatable

<SlidingWindow>.Horizontal_Frame_Width Float default: 2.0 -- animatable

<SlidingWindow>.Vertical_Frame_Width Float default: 2.0 -- animatable

<SlidingWindow>.Frame_Thickness Float default: 0.5 -- animatable

<SlidingWindow>.Glazing_Thickness Float default: 0.25 -- animatable

<SlidingWindow>.Rail_Width Float default: 1.0 -- animatable

<SlidingWindow>.Number_of_Panels_Horizontally Integer default: 1

<SlidingWindow>.Number_of_Panels_Vertically Integer default: 1

<SlidingWindow>.Chamfered_Profile Boolean default: false

<SlidingWindow>.Hung Boolean default: true

<SlidingWindow>.Percent_Open Integer default: 0 -- animatable

<SlidingWindow>.Generate_Mapping_Coords Boolean default: false

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Geometry - Patch Objects

The following list displays the patch objects:

QuadPatch

TriPatch


QuadPatch : GeometryClass

Constructor

quadpatch ...

Properties

<QuadPatch>.length Float default: 25.0 -- animatable

The patch length.

<QuadPatch>.width Float default: 25.0 -- animatable

The patch width.

<QuadPatch>.lengthsegs Integer default: 1 -- animatable, alias: Length_Segments

The number of facets along the length of the grid.

<QuadPatch>.mapCoords Boolean default: false

When on, applies mapping coordinates to the grid.

<QuadPatch>.widthsegs Integer default: 1 -- animatable, alias: Width_Segments

The number of facets along the width of the grid.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


TriPatch : GeometryClass

Constructor

TriPatch ...

Properties

<TriPatch>.length Float default: 25.0 -- animatable

The length of the patch.

<TriPatch>.width Float default: 25.0 -- animatable

The width of the patch.

<TriPatch>.mapCoords Boolean default: false

When on, applies mapping coordinates to the grid.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Geometry - Particle Systems

The following list displays the particle system objects:

Blizzard

PArray

PCloud

Snow

Spray

SuperSpray

Note: Particle Systems are not available in 3D Studio VIZ.


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.


Blizzard : GeometryClass

Constructor

blizzard ...

Note: This class is not available in 3D Studio VIZ.

Properties

Basic Parameters

<Blizzard>.Emitter_Width Float default: 0.0 -- animatable

The width of the emitter icon.

<Blizzard>.Emitter_Length Float default: 0.0 -- animatable

The width of the emitter icon.

<Blizzard>.emitterHidden Boolean default: false

When on, hides the emitter in viewports. When off, the emitter is displayed in viewports. The emitter is never rendered.

<Blizzard>.viewType Integer default: 0

Set the display icon for particles in the viewport:

0- Dots (Displays the particles as dots.)

1- Ticks (Displays the particles as crosses.)

2- Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.)

3- Bbox (For instanced geometry only, this displays each instanced particle, whether a single object, a hierarchy, or a group, as a bounding box.)

<Blizzard>.viewPercent Float default: 10.0 -- percentage, alias: Percentage_Displayed

Sets the percentage of particles displayed in the viewport.

Particle Generation

<Blizzard>.quantityMethod Integer default: 0

Set the method by which the number of particles is determined over time:

0- Use Rate (Specifies a fixed number of particles emitted per frame.)

1- Use Total (Specifies a total number of particles formed over the life of the system.)

Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust, while Use Total is better for bursts of particles over a short period of time.

<Blizzard>.Birth_Rate Integer default: 10 -- animatable

The number of particles emitted per frame.

<Blizzard>.Total_Number Integer default: 100

The total number of particles to be emitted.

<Blizzard>.speed Float default: 10.0 -- animatable

The velocity of the particle at birth, along the normal, in units traveled per frame.

<Blizzard>.Speed_Variation Float default: 0.0 -- animatable, percentage

Percentage of variation to the speed of emission for each particle.

<Blizzard>.tumble Float default: 0.0 -- animatable

Amount of random rotation of the particles.

<Blizzard>.Tumble_Rate Float default: 0.0 -- animatable

Speed at which the particles rotate.

<Blizzard>.Emitter_Start Time default: 0f

The frame at which particles begin to exist in the scene.

<Blizzard>.Emitter_Stop Time default: 30f

The last frame at which particles are emitted.

<Blizzard>.Display_Until Time default: 100f

Time at which all particles will disappear, regardless of other settings.

<Blizzard>.life Time default: 30f -- animatable

The lifespan of each particle from the time of creation.

<Blizzard>.Life_Variation Time default: 0f -- animatable

The number of frames by which the life of each particle can vary from the norm.

<Blizzard>.subsampleCreationTime Boolean default: false

When on, enables the addition of a time offset to the equations of motion that prevents puffing in time.

<Blizzard>.subsampleEmitterTranslation Boolean default: true

If the object-based emitter is moving in space, particles are created at integral times at positions along the geometry's path between renderable positions. This prevents puffing in space.

<Blizzard>.subsampleEmitterRotation Boolean default: true

If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects.

<Blizzard>.size Float default: 1.0 -- animatable

The target size for all particles in the system.

<Blizzard>.Size_Variation Float default: 0.0 -- animatable, percentage

The percentage by which the size of each particle may vary from the norm.

<Blizzard>.Growth_Time Time default: 10f

The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value.

<Blizzard>.Fade_Time Time default: 10f

The number of intervals over which the particle will shrink to 1/10th its Size setting prior to its death.

<Blizzard>.seed Integer default: 0 -- alias: Random_Seed

By changing the Seed value, you achieve different results using otherwise identical particle settings.

Particle Type

<Blizzard>.particleType Integer default: 0

The type of particle emitted:

0- Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra, and so on.)

1- MetaParticles (Uses Metaball particles. These are particle systems in which the individual particles blend together in blobs or streams.)

2- Instanced Geometry (Generates particles that are instances of either an object, a linked hierarchy of objects, or a group.)

<Blizzard>.standardParticle Integer default: 0

standardParticle = 0 - Triangle; 1 - Cube; 2 - Special; 3 - Facing; 4 - Constant; 5 - Tetra; 6 - SixPoint; 7 - Sphere

<Blizzard>.Metaparticle_Tension Float default: 1.0 -- animatable

Determines the tightness of the particles, with regard to their tendency to blend with other particles. The higher the Tension, the harder the blobs, and the harder it is for them to merge.

<Blizzard>.Metaparticle_Tension_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Tension effect.

<Blizzard>.metaballRenderCoarsness Float default: 0.5 -- alias: Metaparticle_Coarseness

The coarseness for metaparticles in the rendered scene.

<Blizzard>.metaballViewCoarsness Float default: 1.0

The coarseness for the viewport display.

<Blizzard>.metaballAutoCoarsness Boolean default: true

When this is on, the rendering coarseness is automatically set, based on the size of the particles, and the viewport coarseness is set to about twice that of the rendering coarseness.

<Blizzard>.Bubble_Amplitude Integer default: 0

Turns on/off One Connected Blob.

0- Off

1- On

<Blizzard>.instancingObject Node default: undefined

The object which is instanced.

<Blizzard>.instanceSubTree Boolean default: false

Turn this on when you want to include the linked children of the picked object in the particle. If the picked object is a group, all children of the group are included.

<Blizzard>.instanceKeyOffsetType Integer default: 0

Set the animation offset keying:

0- None (Each particle duplicates the timing of the original object. As a result, the animation of all particles will be identically timed.)

1- 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.)

2- Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.)

<Blizzard>.instanceFrameOffset Integer default: 0 -- alias: Animation_Offset_Amount

The property value is the UI value times the number of ticks per frame. The number of ticks per frame is accessible via the ticksPerFrame system global variable.

<Blizzard>.mappingType Integer default: 0

Specifies how a mapped material affects the particles:

0- Time (Maps particles over time.)

1- Distance (Maps particles over a distance.)

2- Emitter Fit Planar (Maps particles at birth, based on their point of emission from the rectangular Blizzard emitter icon. The UV range of the mapped material runs from 0 to 1 over the width and length of the emitter.)

<Blizzard>.Mapping_Time_Base Time default: 30f -- animatable

The number of frames from the birth of the particle that it takes to complete one mapping of the particle.

<Blizzard>.Mapping_Distance_Base Float default: 100.0 -- animatable

The distance, in units, from the birth of the particle that it takes to complete one mapping of the particle.

<Blizzard>.materialSource Integer default: 0

Updates the material carried by the particle system, using the source specified:

0- Icon (The particles use the material currently assigned to the particle system icon.)

1- Instanced Geometry (The particles use the material assigned to the instanced geometry.)

Rotation and Collision

<Blizzard>.Spin_Time Time default: 30f -- animatable

The number of frames for one rotation of a particle. If set to 0, no rotation takes place.

<Blizzard>.Spin_Time_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Spin Time.

<Blizzard>.Spin_Phase Float default: 0.0 -- animatable, angle

The initial particle rotation, in degrees.

<Blizzard>.Spin_Phase_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Phase.

<Blizzard>.spinAxisType Integer default: 0

The spin axis for the particles:

0- Random (The spin axis for each of the particles is random.)

1- User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)

<Blizzard>.X_Spin_Vector Float default: 1.0 -- animatable

Spin vector of the X-axis.

<Blizzard>.Y_Spin_Vector Float default: 0.0 -- animatable

Spin vector of the Y-axis.

<Blizzard>.Z_Spin_Vector Float default: 0.0 -- animatable

Spin vector of the Z-axis.

<Blizzard>.Spin_Axis_Variation Float default: 0.0 -- animatable, angle

The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings.

<Blizzard>.Interparticle_Collisions_On Integer default: 0

Turn on/off interparticle collisions:

0- Off

1- On

<Blizzard>.Interparticle_Collision_Steps Integer default: 2

The number of intervals per rendering interval, during which an inter-particle collision test is conducted. The higher the value, the more accurate the simulation, but the slower the simulation will run.

<Blizzard>.Interparticle_Collision_Bounce Float default: 100.0 -- animatable, percentage

The degree to which speed is recovered after a collision.

<Blizzard>.Interparticle_Collision_Bounce_Variation Float default: 0.0 -- animatable, percentage

The percentage of random variation of the Bounce value, applied to the particles.

Object Motion Inheritance

<Blizzard>.motionInfluence Float default: 100.0 -- animatable, alias: Object_Motion_Inheritance

The percent of particles that inherit the motion of the object-based emitter at the moment of particle formation.

<Blizzard>.motionMultiplier Float default: 1.0 -- animatable, alias: Object_Motion_Multiplier

Modifies the amount by which the emitter motion affects the particle motion. This can be a positive or negative number.

<Blizzard>.motionVariation Float default: 0.0 -- animatable, percentage; alias: Object_Motion_Multiplier_Variation

Percentage of variation of the Multiplier value.

Particle Spawn

<Blizzard>.spawnType Integer default: 0

Determines what happens to particles at either collision or death:

0- 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.)

1- Die After Collision (Particles disappear when they strike a deflector to which they're bound, such as the SDeflector.)

2- Spawn on Collision (Spawn effects take place upon collision with a bound deflector.)

3- Spawn on Death (Spawn effects take place at the end of each particle's life.)

4- Spawn Trails (Particles are spawned from existing particles at each frame of that particle's life.)

<Blizzard>.Die__X_frames_after_collision Time default: 0f -- animatable

The life, in frames, that the particle will persist after the collision. Setting this to 0 (the default) causes particles to vanish immediately after the collision.

<Blizzard>.Die__X_frames_after_collision_variation Float default: 0.0 -- animatable, percentage

Varies the Persist value of each particle, when Persist is greater than 0. This lets you "feather" the dying off of the particle density.

<Blizzard>.Spawn_Affects Integer default: 100

The percentage of particles that will spawn. Reducing this reduces the number of particles that produce spawned particles.

<Blizzard>.Spawn_Multiplier_Variation Float default: 0.0 -- percentage

Percentage range by which the Multiplier value will vary, frame by frame.

<Blizzard>.Spawn_Direction_Chaos Float default: 0.0 -- animatable

The amount by which the direction of the spawned particle can vary from the direction of the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned particle to travel in any random direction. A setting of 50 causes the spawned particle to deviate from its parent's path by up to 90 degrees.

<Blizzard>.Spawn_Speed_Chaos Float default: 0.0 -- animatable

The range of a percentage of change in the speed of the spawned particle relative to its parent. A value of 0 means no change.

<Blizzard>.spawnSpeedType Integer default: 0

Sets the type of speed applied to spawn particles:

0- Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the spawned particles.)

1- Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.)

2- Both (Some particles speed up, while others slow down, based on the .spawn_Speed_Chaos value.)

<Blizzard>.spawnInheritVelocity Boolean default: false

When on, spawned particles inherit the speed of their parents, in addition to the effect of the .spawn_Speed_Chaos value.

<Blizzard>.spawnSpeedFixed Boolean default: false

When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range applied randomly to each particle.

<Blizzard>.lifespanValueQueue Array default: #()

lifespanValueQueue is an array of integers which correspond to lifespan values for each spawned generation of particles.

<Blizzard>.objectMutationQueue Array default: #()

objectMutationQueue is an array of nodes which correspond to instanced-object particle types. Each generation of spawning will use the next node as its object type.

See also

Particle System Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


PArray : GeometryClass

Constructor

parray ...

Note: This class is not available in 3D Studio VIZ.

Properties

Basic Parameters

<PArray>.emitter Node default: undefined

The object which acts as an emitter.

<PArray>.formation Integer default: 0 -- alias: Emitter_Distribution

Set the emitter distribution type:

0- Over Entire Surface (Emits particles randomly over the entire surface of the object-based emitter.)

1- Along Visible Edges (Emits particles randomly from the visible edges of the object.)

2- At All Vertices (Emits particles from the vertices of the object.)

3- At Distinct Points (Places a specified number of emitter points randomly over the surface of the object.)

4- At Face Centers (Emits particles from the center of each triangular face.)

<PArray>.numDistinctPoints Integer default: 20 -- alias: Number_of_Emitters

The number of emitter points used when At Distinct Points is chosen.

<PArray>.Use_Selected_Subobjects Integer default: 0 -- animatable

With mesh-based emitters, this limits the source of the particle stream to the sub-object selection passed up the modifier stack in the object-based emitter.

0- Off

1- On

<PArray>.iconsize Float default: 20.0 -- alias: Emitter_Width

The width of the emitter icon.

<PArray>.iconHidden Boolean default: false

When on, hides the emitter in viewports. When off, the emitter is displayed in viewports. The emitter is never rendered.

<PArray>.viewType Integer default: 0

Set the display icon for particles in the viewport:

0- Dots (Displays the particles as dots.)

1- Ticks (Displays the particles as crosses.)

2- Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.)

3- Bbox (For instanced geometry only, this displays each instanced particle, whether a single object, a hierarchy, or a group, as a bounding box.)

<PArray>.viewPercent Float default: 10.0 -- percentage, alias: Percentage_Displayed

The percentage of particles displayed in the viewport.

Particle Generation

<PArray>.quantityMethod Integer default: 0

Set the method by which the number of particles is determined over time:

0- Use Rate (Specifies a fixed number of particles emitted per frame.)

1- Use Total (Specifies a total number of particles formed over the life of the system.)

Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust, while Use Total is better for bursts of particles over a short period of time.

<PArray>.Birth_Rate Integer default: 10 -- animatable

The number of particles emitted per frame.

<PArray>.Total_Number Integer default: 100

The total number of particles to be emitted.

<PArray>.speed Float default: 10.0 -- animatable

The velocity of the particle at birth, along the normal, in units traveled per frame.

<PArray>.Speed_Variation Float default: 0.0 -- animatable, percentage

Percentage of variation to the speed of emission for each particle.

<PArray>.Divergence_Angle Float default: 10.0 -- animatable, angle

Applies an angular degree of variation by which each particle's velocity can vary from the emitter normal.

<PArray>.Emitter_Start Time default: 0f

The frame at which particles begin to exist in the scene.

<PArray>.Emitter_Stop Time default: 30f

The last frame at which particles are emitted.

<PArray>.Display_Until Time default: 100f

Time at which all particles will disappear, regardless of other settings.

<PArray>.life Time default: 30f -- animatable

The lifespan of each particle from the time of creation.

<PArray>.Life_Variation Time default: 0f -- animatable

The number of frames by which the life of each particle can vary from the norm.

<PArray>.subsampleCreationTime Boolean default: false

When on, enables the addition of a time offset to the equations of motion that prevents puffing in time.

<PArray>.subsampleEmitterTranslation Boolean default: true

If the object-based emitter is moving in space, particles are created at integral times at positions along the geometry's path between renderable positions. This prevents puffing in space.

<PArray>.subsampleEmitterRotation Boolean default: true

If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects.

<PArray>.size Float default: 1.0 -- animatable

The target size for all particles in the system.

<PArray>.Size_Variation Float default: 0.0 -- animatable, percentage

The percentage by which the size of each particle may vary from the norm.

<PArray>.Growth_Time Time default: 10f

The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value.

<PArray>.Fade_Time Time default: 10f

The number of intervals over which the particle will shrink to 1/10th its Size setting prior to its death.

<PArray>.seed Integer default: 0 -- alias: Random_Seed

By changing the Seed value, you achieve different results using otherwise identical particle settings.

Particle Type

<PArray>.particleType Integer default: 0

The type of particle emitted:

0- Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra, and so on.)

1- MetaParticles (Uses Metaball particles. These are particle systems in which the individual particles blend together in blobs or streams.)

2- Object Fragments (Creates particles out of fragments of an object.)

3- Instanced Geometry (Generates particles that are instances of either an object, a linked hierarchy of objects, or a group.)

<PArray>.standardParticle Integer default: 0

Set the type of particle used when standard particles is selected:

0- Triangle (Renders each particle as a triangle. Use Triangle particles with noise opacity for steam or smoke.)

1- Cube (Renders each particle as a cube.)

2- 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.)

3- Facing (Renders each particle as a square that always faces the view. Use with an appropriate opacity map for bubbles or snowflakes.)

4- 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.)

5- 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.)

6- SixPoint (Renders each particle as a six-pointed, two-dimensional star.)

7- Sphere (Renders each particle as a sphere.)

<PArray>.Metaparticle_Tension Float default: 1.0 -- animatable

Determines the tightness of the particles, with regard to their tendency to blend with other particles. The higher the Tension, the harder the blobs, and the harder it is for them to merge.

<PArray>.Metaparticle_Tension_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Tension effect.

<PArray>.metaballRenderCoarsness Float default: 0.5 -- alias: Metaparticle_Coarseness

The coarseness for metaparticles in the rendered scene.

<PArray>.metaballViewCoarsness Float default: 1.0

The coarseness for the viewport display.

<PArray>.metaballAutoCoarsness Boolean default: true

When this is on, the rendering coarseness is automatically set, based on the size of the particles, and the viewport coarseness is set to about twice that of the rendering coarseness.

<PArray>.fragmentMethod Integer default: 0

Method for object fragment particles:

0- All Faces (Each face of the object becomes a particle. This results in triangular particles.)

1- Number of Chunks (The object breaks into irregular fragments.)

2- Smoothing Angle (The fragments are broken based on the angles between face normals, as specified in the fragSmoothingAngle value. Generally, the higher the value, the fewer the number of fragments.)

<PArray>.Fragment_Thickness Float default: 1.0

Sets the thickness of the fragments. At 0, the fragments are single-sided with no thickness. When greater than 0, the fragments are extruded, at fragmentation time, by the amount specified. The outer and inner surfaces of the fragment use identical smoothing, which is picked up from the object-based emitter. The edges of the fragments are not smoothed.

<PArray>.fragChunkMinimum Integer default: 100 -- alias: Fragment_Count

Determines a number of "seed" faces in the geometry. Each seed face collects connecting faces surrounding it until all available faces are exhausted. Any leftover faces become unique particles, thus increasing the minimum number of fragments.

<PArray>.fragSmoothingAngle Float default: 0.0

Sets the amount of smoothing angle.

<PArray>.instancingObject Node default: undefined

The object which is instanced.

<PArray>.instanceSubTree Boolean default: false

Turn this on when you want to include the linked children of the picked object in the particle. If the picked object is a group, all children of the group are included.

<PArray>.instanceKeyOffsetType Integer default: 0

Set the animation offset keying:

0- None (Each particle duplicates the timing of the original object. As a result, the animation of all particles will be identically timed.)

1- 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.)

2- Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.)

<PArray>.instanceFrameOffset Integer default: 0 -- alias: Animation_Offset_Amount

The property value is the UI value times the number of ticks per frame. The number of ticks per frame is accessible via the ticksPerFrame system global variable.

<PArray>.mappingType Integer default: 0

Specifies how a mapped material affects the particles:

0- Time (Maps particles over time.)

1- Distance (Maps particles over a distance.)

<PArray>.Mapping_Time_Base Time default: 30f -- animatable

The number of frames from the birth of the particle that it takes to complete one mapping of the particle.

<PArray>.Mapping_Distance_Base Float default: 100.0 -- animatable

The distance, in units, from the birth of the particle that it takes to complete one mapping of the particle.

<PArray>.materialSource Integer default: 0

Updates the material carried by the particle system, using the source specified:

0- Icon (The particles use the material currently assigned to the particle system icon.)

1- Picked Emitter (The particles use the material assigned to the distribution object.)

2- Instanced Geometry (The particles use the material assigned to the instanced geometry.)

<PArray>.fragOutsideMatID Integer default: 0

Specifies which face ID number is assigned to the outside faces of the fragments. This defaults to 0, which is not a valid ID number, forcing the outside of the particle fragments to use whatever material is currently assigned to the associated faces. Thus, if your distribution object already has several submaterials assigned to its outer faces, these materials are retained by using ID 0. If you want a single, specific submaterial, you can assign it by changing this value.

<PArray>.fragEdgeMatID Integer default: 2

Specifies which submaterial ID number is assigned to the edges of the fragments.

<PArray>.fragBackMatID Integer default: 3

Specifies which submaterial ID number is assigned to the back sides of the fragments.

Rotation and Collision

<PArray>.Spin_Time Time default: 0f -- animatable

The number of frames for one rotation of a particle. If set to 0, no rotation takes place.

<PArray>.Spin_Time_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Spin Time.

<PArray>.Spin_Phase Float default: 0.0 -- animatable, angle

The initial particle rotation, in degrees.

<PArray>.Spin_Phase_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Phase.

<PArray>.spinAxisType Integer default: 0

The spin axis for the particles:

0- Random (The spin axis for each of the particles is random.)

1- Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in which they're moving.)

2- User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)

<PArray>.Blur_Stretch Integer default: 0 -- animatable

When greater than 0, the particles stretch along the travel axis, depending on their speed. Specifically, the Stretch value specifies the percent of their length per each unit of the Speed setting (in the Particle Motion group). Thus, if you set Stretch to 2 while Speed is set at 10, the particles are stretched 20 percent longer than their original size along the axis of their travel. This value is only available when you choose Direction of Travel/Mblur.

<PArray>.X_Spin_Vector Float default: 1.0 -- animatable

Spin vector of the X-axis.

<PArray>.Y_Spin_Vector Float default: 0.0 -- animatable

Spin vector of the Y-axis.

<PArray>.Z_Spin_Vector Float default: 0.0 -- animatable

Spin vector of the Z-axis.

<PArray>.Spin_Axis_Variation Float default: 0.0 -- animatable, angle

The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings.

<PArray>.Interparticle_Collisions_On Integer default: 0

Turn on/off interparticle collisions:

0- Off

1- On

<PArray>.Interparticle_Collision_Steps Integer default: 2

The number of intervals per rendering interval, during which an inter-particle collision test is conducted. The higher the value, the more accurate the simulation, but the slower the simulation will run.

<PArray>.Interparticle_Collision_Bounce Float default: 100.0 -- animatable, percentage

The degree to which speed is recovered after a collision.

<PArray>.Interparticle_Collision_Bounce_Variation Float default: 0.0 -- animatable, percentage

The percentage of random variation of the Bounce value, applied to the particles.

Object Motion Inheritance

<PArray>.motionInfluence Float default: 100.0 -- animatable, alias: Object_Motion_Inheritance

The percent of particles that inherit the motion of the object-based emitter at the moment of particle formation.

<PArray>.motionMultiplier Float default: 1.0 -- animatable, alias: Object_Motion_Multiplier

Modifies the amount by which the emitter motion affects the particle motion. This can be a positive or negative number.

<PArray>.motionVariation Float default: 0.0 -- animatable, percentage; alias: Object_Motion_Multiplier_Variation

Percentage of variation of the Multiplier value.

Bubble Motion

<PArray>.Bubble_Amplitude Float default: 0.0 -- animatable

The distance the particle moves off its usual velocity vector as it travels.

<PArray>.Bubble_Amplitude_Variation Float default: 0.0 -- animatable, percentage

The percent of Amplitude variation applied to each particle.

<PArray>.Bubble_Period Time default: 100000f -- animatable

The cycle time for one complete oscillation of a particle through the bubble "wave." A recommended value might be 20-30 intervals.

<PArray>.Bubble_Period_Variation Float default: 0.0 -- animatable, percentage

The percent of Period variation for each particle.

<PArray>.Bubble_Phase Float default: 0.0 -- animatable, angle

The initial displacement of the bubble pattern along the vector.

<PArray>.Bubble_Phase_Variation Float default: 0.0 -- animatable, percentage

The percent of Phase variation for each particle.

Particle Spawn

<PArray>.spawnType Integer default: 0

Determines what happens to particles at either collision or death:

0- 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.)

1- Die After Collision (Particles disappear when they strike a deflector to which they're bound, such as the SDeflector.)

2- Spawn on Collision (Spawn effects take place upon collision with a bound deflector.)

3- Spawn on Death (Spawn effects take place at the end of each particle's life.)

4- Spawn Trails (Particles are spawned from existing particles at each frame of that particle's life.)

<PArray>.Die__X_frames_after_collision Time default: 0f -- animatable

The life, in frames, that the particle will persist after the collision. Setting this to 0 (the default) causes particles to vanish immediately after the collision.

<PArray>.Die__X_frames_after_collision_variation Float default: 0.0 -- animatable, percentage

Varies the Persist value of each particle, when Persist is greater than 0. This lets you "feather" the dying off of the particle density.

<PArray>.Spawn_Generations Integer default: 1

The number of spawns beyond the original particle generation. For example, if this is set to 1, and you're spawning at death, one spawning will occur beyond the original lifespan of each particle.

<PArray>.Spawn_Affects Integer default: 100

The percentage of particles that will spawn. Reducing this reduces the number of particles that produce spawned particles.

<PArray>.Spawn_Multiplier Integer default: 1

Multiplies the number of particles spawned at each spawning event.

<PArray>.Spawn_Multiplier_Variation Float default: 0.0 -- percentage

Percentage range by which the Multiplier value will vary, frame by frame.

<PArray>.Spawn_Direction_Chaos Float default: 0.0 -- animatable, percentage

The amount by which the direction of the spawned particle can vary from the direction of the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned particle to travel in any random direction. A setting of 50 causes the spawned particle to deviate from its parent's path by up to 90 degrees.

<PArray>.Spawn_Speed_Chaos Float default: 0.0 -- animatable

Random percentage range of scaling of the spawned particles relative to their parents, and dependent on the options below.

<PArray>.spawnSpeedType Integer default: 0

Sets the type of speed applied to spawn particles:

0- Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the spawned particles.)

1- Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.)

2- Both (Some particles speed up, while others slow down, based on the .spawn_Speed_Chaos value.)

<PArray>.spawnInheritVelocity Boolean default: false

When on, spawned particles inherit the speed of their parents, in addition to the effect of the .spawn_Speed_Chaos value.

<PArray>.spawnSpeedFixed Boolean default: false

When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range applied randomly to each particle.

<PArray>.Spawn_Scale_Chaos Float default: 0.0 -- animatable

The range of a percentage of change in the speed of the spawned particle relative to its parent. A value of 0 means no change.

<PArray>.spawnScaleType Integer default: 0

The type of speed scaling for the spawned particles:

0- Slow (Applies the speed factor randomly to slow the speed of the spawned particles.)

1- Fast (Randomly speeds up particles based on the speed factor.)

2- Both (Some particles speed up, while others slow down, based on the speed factor.)

<PArray>.spawnScaleFixed Boolean default: false

When on, uses the .spawn_Scale_Chaos value as a set value, rather than as a range applied randomly to each particle.

<PArray>.lifespanValueQueue Array default: #()

lifespanValueQueue is an array of integers which correspond to lifespan values for each spawned generation of particles.

<PArray>.Spawn_Lifespan Integer default: 0

Value that sets initial lifespan of spawned particles.

<PArray>.objectMutationQueue Array default: #()

objectMutationQueue is an array of nodes which correspond to instanced-object particle types. Each generation of spawning will use the next node as its object type.

See also

Particle System Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


PCloud : GeometryClass

Constructor

pcloud ...

Note: This class is not available in 3D Studio VIZ.

Properties

Basic Parameters

<PCloud>.emitter Node default: undefined

The object which acts as an emitter.

<PCloud>.formation Integer default: 0

Set the emitter formation:

0- Box Emitter

1- Sphere Emitter

2- Cylinder Emitter

3- Object-based Emitter

<PCloud>.Emitter_Rad_Len Float default: 0.0 -- animatable

The radius of a spherical or cylindrical icon, and the length of a box icon.

<PCloud>.Emitter_Width Float default: 0.0 -- animatable

The width of a box emitter.

<PCloud>.Emitter_Height Float default: 0.0 -- animatable

The height of a box or cylindrical emitter.

<PCloud>.emitterHidden Boolean default: false

Hides the emitter in the viewport, when on.

Note: the emitter is never rendered.

<PCloud>.viewType Integer default: 0

Set the display icon for particles in the viewport:

0- Dots (Displays the particles as dots.)

1- Ticks (Displays the particles as crosses.)

2- Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.)

3- Bbox (For instanced geometry only, this displays each instanced particle, whether a single object, a hierarchy, or a group, as a bounding box.)

<PCloud>.viewPercent Float default: 10.0 -- percentage, alias: Percentage_Displayed

The percentage of particles displayed in the viewport.

Particle Generation

<PCloud>.quantityMethod Integer default: 0

Set the method by which the number of particles is determined over time:

0- Use Rate (Specifies a fixed number of particles emitted per frame.)

1- Use Total (Specifies a total number of particles formed over the life of the system.)

Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust, while Use Total is better for bursts of particles over a short period of time.

<PCloud>.Birth_Rate Integer default: 10 -- animatable

The number of particles emitted per frame.

<PCloud>.Total_Number Integer default: 100

The total number of particles to be emitted.

<PCloud>.speed Float default: 0.0 -- animatable

The velocity of the particle at birth, along the normal, in units traveled per frame.

<PCloud>.Speed_Variation Float default: 0.0 -- animatable, percentage

Percentage of variation to the speed of emission for each particle.

<PCloud>.motionType Integer default: 0

Set the particle's motionType

0- Random Direction (This option emits particles in random directions.)

1- Enter Vector (The direction of the particles is determined by a vector defined by the three X, Y, and Z vectors.)

2- Reference Object (Emits particles in the direction of the local Z axis of a specified object.)

<PCloud>.Direction_Vector_X Float default: 1.0 -- animatable

The particle direction vectors for the X-axis.

<PCloud>.Direction_Vector_Y Float default: 0.0 -- animatable

The particle direction vectors for the Y-axis.

<PCloud>.Direction_Vector_Z Float default: 0.0 -- animatable

The particle direction vectors for the Z-axis.

<PCloud>.motionReferenceObject Node default: undefined

The object used as the reference object.

<PCloud>.directionVariation Float default: 0.0 -- animatable, percentage, alias: Speed_Direction_Variation

Percentage of variation to the direction when you choose either the Direction Vector or Reference Object option.

<PCloud>.Emitter_Start Time default: 0f

The frame at which particles begin to exist in the scene.

<PCloud>.Emitter_Stop Time default: 0f

The last frame at which particles are emitted.

<PCloud>.Display_Until Time default: 100f

Time at which all particles will disappear, regardless of other settings.

<PCloud>.life Time default: 101f -- animatable

The lifespan of each particle from the time of creation.

<PCloud>.Life_Variation Time default: 0f -- animatable

The number of frames by which the life of each particle can vary from the norm.

<PCloud>.size Float default: 1.0 -- animatable

The target size for all particles in the system.

<PCloud>.Size_Variation Float default: 0.0 -- animatable, percentage

The percentage by which the size of each particle may vary from the norm.

<PCloud>.Growth_Time Time default: 0f

The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value.

<PCloud>.Fade_Time Time default: 0f

The number of intervals over which the particle will shrink to 1/10th its Size setting prior to its death.

<PCloud>.seed Integer default: 0 -- alias: Random_Seed

By changing the Seed value, you achieve different results using otherwise identical particle settings.

Particle Type

<PCloud>.particleType Integer default: 0

The type of particle emitted:

0- Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra, and so on.)

1- MetaParticles (Uses Metaball particles. These are particle systems in which the individual particles blend together in blobs or streams.)

2- Instanced Geometry (Generates particles that are instances of either an object, a linked hierarchy of objects, or a group.)

<PCloud>.standardParticle Integer default: 0

Set the type of particle used when standard particles is selected:

0- Triangle (Renders each particle as a triangle. Use Triangle particles with noise opacity for steam or smoke.)

1- Cube (Renders each particle as a cube.)

2- 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.)

3- Facing (Renders each particle as a square that always faces the view. Use with an appropriate opacity map for bubbles or snowflakes.)

4- 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.)

5- 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.)

6- SixPoint (Renders each particle as a six-pointed, two-dimensional star.)

7- Sphere (Renders each particle as a sphere.)

<PCloud>.Metaparticle_Tension Float default: 1.0 -- animatable

Determines the tightness of the particles, with regard to their tendency to blend with other particles. The higher the Tension, the harder the blobs, and the harder it is for them to merge.

<PCloud>.Metaparticle_Tension_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Tension effect.

<PCloud>.metaballRenderCoarsness Float default: 0.5 -- alias: Metaparticle_Coarseness

The coarseness for metaparticles in the rendered scene.

<PCloud>.metaballViewCoarsness Float default: 1.0

The coarseness for the viewport display.

<PCloud>.metaballAutoCoarsness Boolean default: true

When this is on, the rendering coarseness is automatically set, based on the size of the particles, and the viewport coarseness is set to about twice that of the rendering coarseness.

<PCloud>.instancingObject Node default: undefined

The object which is instanced.

<PCloud>.instanceSubTree Boolean default: false

Turn this on when you want to include the linked children of the picked object in the particle. If the picked object is a group, all children of the group are included.

<PCloud>.instanceKeyOffsetType Integer default: 0

Set the animation offset keying:

0- None (Each particle duplicates the timing of the original object. As a result, the animation of all particles will be identically timed.)

1- 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.)

2- Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.)

<PCloud>.instanceFrameOffset Integer default: 0 -- alias: Animation_Offset_Amount

The property value is the UI value times the number of ticks per frame. The number of ticks per frame is accessible via the ticksPerFrame system global variable.

<PCloud>.mappingType Integer default: 0

Specifies how a mapped material affects the particles:

0- Time (Maps particles over time.)

1- Distance (Maps particles over a distance.)

<PCloud>.Mapping_Time_Base Time default: 30f -- animatable

The number of frames from the birth of the particle that it takes to complete one mapping of the particle.

<PCloud>.Mapping_Distance_Base Float default: 100.0 -- animatable

The distance, in units, from the birth of the particle that it takes to complete one mapping of the particle.

<PCloud>.materialSource Integer default: 0

Updates the material carried by the particle system, using the source specified:

0- Icon (The particles use the material currently assigned to the particle system icon.)

1- Instanced Geometry (The particles use the material assigned to the instanced geometry.)

Rotation and Collision

<PCloud>.Spin_Time Time default: 0f—animatable

The number of frames for one rotation of a particle. If set to 0, no rotation takes place.

<PCloud>.Spin_Time_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Spin Time.

<PCloud>.Spin_Phase Float default: 0.0 -- animatable, angle

The initial particle rotation, in degrees.

<PCloud>.Spin_Phase_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Phase.

<PCloud>.spinAxisType Integer default: 0

The spin axis for the particles:

0- Random (The spin axis for each of the particles is random.)

1- Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in which they're moving.)

2- User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)

<PCloud>.Blur_Stretch Integer default: 0 -- animatable

When greater than 0, the particles stretch along the travel axis, depending on their speed. Specifically, the Stretch value specifies the percent of their length per each unit of the Speed setting (in the Particle Motion group). Thus, if you set Stretch to 2 while Speed is set at 10, the particles are stretched 20 percent longer than their original size along the axis of their travel. This value is only available when you choose Direction of Travel/Mblur.

<PCloud>.X_Spin_Vector Float default: 1.0 -- animatable

Spin vector of the X-axis.

<PCloud>.Y_Spin_Vector Float default: 0.0 -- animatable

Spin vector of the Y-axis.

<PCloud>.Z_Spin_Vector Float default: 0.0 -- animatable

Spin vector of the Z-axis.

<PCloud>.Spin_Axis_Variation Float default: 0.0 -- animatable, angle

The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings.

<PCloud>.Interparticle_Collisions_On Integer default: 0

Turn on/off interparticle collisions:

0- Off

1- On

<PCloud>.Interparticle_Collision_Steps Integer default: 2

The number of intervals per rendering interval, during which an inter-particle collision test is conducted. The higher the value, the more accurate the simulation, but the slower the simulation will run.

<PCloud>.Interparticle_Collision_Bounce Float default: 100.0 -- animatable, percentage

The degree to which speed is recovered after a collision.

<PCloud>.Interparticle_Collision_Bounce_Variation Float default: 0.0 -- animatable, percentage

The percentage of random variation of the Bounce value, applied to the particles.

Object Motion Inheritance

<PCloud>.motionInfluence Float default: 100.0 -- animatable, alias: Object_Motion_Inheritance

The percent of particles that inherit the motion of the object-based emitter at the moment of particle formation.

<PCloud>.motionMultiplier Float default: 1.0 -- animatable, alias: Object_Motion_Multiplier

Modifies the amount by which the emitter motion affects the particle motion. This can be a positive or negative number.

<PCloud>.motionVariation Float default: 0.0 -- animatable, percentage; alias: Object_Motion_Multiplier_Variation

Percentage of variation of the Multiplier value.

Bubble Motion

<PCloud>.Bubble_Amplitude Float default: 0.0 -- animatable

The distance the particle moves off its usual velocity vector as it travels.

<PCloud>.Bubble_Amplitude_Variation Float default: 0.0 -- animatable, percentage

The percent of Amplitude variation applied to each particle.

<PCloud>.Bubble_Period Time default: 100000f—animatable

The cycle time for one complete oscillation of a particle through the bubble "wave." A recommended value might be 20-30 intervals.

<PCloud>.Bubble_Period_Variation Float default: 0.0 -- animatable, percentage

The percent of Period variation for each particle.

<PCloud>.Bubble_Phase Float default: 0.0 -- animatable, angle

The initial displacement of the bubble pattern along the vector.

<PCloud>.Bubble_Phase_Variation Float default: 0.0 -- animatable, percentage

The percent of Phase variation for each particle.

Particle Spawn

<PCloud>.spawnType Integer default: 0

Determines what happens to particles at either collision or death:

0- 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.)

1- Die After Collision (Particles disappear when they strike a deflector to which they're bound, such as the SDeflector.)

2- Spawn on Collision (Spawn effects take place upon collision with a bound deflector.)

3- Spawn on Death (Spawn effects take place at the end of each particle's life.)

4- Spawn Trails (Particles are spawned from existing particles at each frame of that particle's life.)

<PCloud>.Die__X_frames_after_collision Time default: 0f -- animatable

The life, in frames, that the particle will persist after the collision. Setting this to 0 (the default) causes particles to vanish immediately after the collision.

<PCloud>.Die__X_frames_after_collision_variation Float default: 0.0 -- animatable, percentage

Varies the Persist value of each particle, when Persist is greater than 0. This lets you "feather" the dying off of the particle density.

<PCloud>.Spawn_Generations Integer default: 1

The number of spawns beyond the original particle generation. For example, if this is set to 1, and you're spawning at death, one spawning will occur beyond the original lifespan of each particle.

<PCloud>.Spawn_Multiplier Integer default: 1

Multiplies the number of particles spawned at each spawning event.

<PCloud>.Spawn_Direction_Chaos Float default: 0.0 -- animatable, percentage

The amount by which the direction of the spawned particle can vary from the direction of the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned particle to travel in any random direction. A setting of 50 causes the spawned particle to deviate from its parent's path by up to 90 degrees.

<PCloud>.Spawn_Speed_Chaos Float default: 0.0 -- animatable

Random percentage range of scaling of the spawned particles relative to their parents, and dependent on the options below.

<PCloud>.spawnSpeedType Integer default: 0

Sets the type of speed applied to spawn particles:

0- Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the spawned particles.)

1- Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.)

2- Both (Some particles speed up, while others slow down, based on the .spawn_Speed_Chaos value.)

<PCloud>.spawnInheritVelocity Boolean default: false

When on, spawned particles inherit the speed of their parents, in addition to the effect of the .spawn_Speed_Chaos value.

<PCloud>.spawnSpeedFixed Boolean default: false

When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range applied randomly to each particle.

<PCloud>.Spawn_Scale_Chaos Float default: 0.0 -- animatable

The range of a percentage of change in the speed of the spawned particle relative to its parent. A value of 0 means no change.

<PCloud>.spawnScaleType Integer default: 0

The type of speed scaling for the spawned particles:

0- Slow (Applies the speed factor randomly to slow the speed of the spawned particles.)

1- Fast (Randomly speeds up particles based on the speed factor.)

2- Both (Some particles speed up, while others slow down, based on the speed factor.)

<PCloud>.spawnScaleFixed Boolean default: false

When on, uses the .spawn_Scale_Chaos value as a set value, rather than as a range applied randomly to each particle.

<PCloud>.lifespanValueQueue Array default: #()

lifespanValueQueue is an array of integers which correspond to lifespan values for each spawned generation of particles.

<PCloud>.Spawn_Lifespan Integer default: 0

Value that sets initial lifespan of spawned particles.

<PCloud>.objectMutationQueue Array default: #()

objectMutationQueue is an array of nodes which correspond to instanced-object particle types. Each generation of spawning will use the next node as its object type.

See also

Particle System Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Snow : GeometryClass

Constructor

snow ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Snow>.viewportcount Integer default: 100

Maximum number of particles displayed in viewports at any given frame.

<Snow>.rendercount Integer default: 100

Maximum number of particles that can appear in a single frame when you render it.

<Snow>.flakesize Float default: 2.0 -- animatable, alias: Flake_Size

Size of a particle in the active units.

<Snow>.speed Float default: 10.0 -- animatable

Initial velocity of each particle as it leaves the emitter. Particles travel at this speed unless they are affected by a particle system space warp.

<Snow>.variation Float default: 2.0 -- animatable

Varies the initial speed and direction of particles. The greater the Variation, the broader the area of snowfall.

<Snow>.tumble Float default: 0.0 -- animatable

Amount of random rotation for snowflake particles. This parameter can range from 0 to 1. At 0, flakes do not rotate; at 1, they rotate the most. The axis of rotation is generated randomly for each particle.

<Snow>.tumblescale Float default: 1.0 -- animatable, alias: Tumble_Rate

Speed at which snowflakes rotate. The greater the Tumble Rate, the faster the rotation.

<Snow>.display Integer default: 0

Set how particles are displayed in viewports:

0- Flakes (star-shaped snowflakes)

1- Dots

2- Ticks

<Snow>.render Integer default: 0

Set how particles are rendered:

0- 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.)

1- Triangle (Each particle is rendered as a triangle. Only one side of the triangle is a face to which you can assign a material.)

2- Facing (Particles are rendered as square faces whose width and height equal Flake Size. Facing particles are provided especially for use with material maps.)

<Snow>.start Time default: 0f -- alias: starttime

Number of the first frame where particles appear.

<Snow>.lifetime Time default: 30f -- alias: life

The lifetime of a particle, in number of frames.

<Snow>.birthrate Time default: 0f -- animatable, alias: Birth_Rate

The number of new particles born per frame. If this is less than or equal to the maximum sustainable rate, the particle system generates an even flow of particles. If it is greater than the maximum rate, the particle system generates particles in bursts.

<Snow>.constant Boolean default: true

When on, Birth Rate is unavailable and the birth rate used equals the maximum sustainable rate. When off, Birth Rate is available. Turning Constant off does not mean that the birth rate varies automatically; the birth rate remains constant unless you animate the Birth Rate parameter.

<Snow>.emitterwidth Float default: 25.0 -- animatable, alias: width

The width of the emitter.

<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

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Spray : GeometryClass

Constructor

spray …

Note: This class is not available in 3D Studio VIZ.

Properties

<Spray>.viewportcount Integer default: 100

Maximum number of particles displayed in viewports at any given frame.

<Spray>.rendercount Integer default: 100

Maximum number of particles that can appear in a single frame when you render it.

<Spray>.dropsize Float default: 2.0 -- animatable, alias: Drop_Size

Size of a particle in the active units.

<Spray>.speed Float default: 10.0 -- animatable

Initial velocity of each particle as it leaves the emitter. Particles travel at this speed unless they are affected by a particle system space warp.

<Spray>.variation Float default: 2.0 -- animatable

Varies the initial speed and direction of particles. The greater the Variation, the broader the area of snowfall.

<Spray>.display Integer default: 0

Set how particles are displayed in viewports:

0- Drops (streaks)

1- Dots

2- Ticks

<Spray>.render Integer default: 0

Set how particles are rendered:

0- 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.)

1- Facing (Particles are rendered as square faces whose width and height equal Drop Size. Facing particles are provided especially for use with material maps.)

<Spray>.start Time default: 0f -- alias: starttime

Number of the first frame where particles appear.

<Spray>.lifetime Time default: 30f -- animatable, alias: life

The lifetime of a particle, in number of frames.

<Spray>.birthrate Time default: 0f -- animatable, alias: Birth_Rate

The number of new particles born per frame. If this is less than or equal to the maximum sustainable rate, the particle system generates an even flow of particles. If it is greater than the maximum rate, the particle system generates particles in bursts.

<Spray>.constant Boolean default: true

When on, Birth Rate is unavailable and the birth rate used equals the maximum sustainable rate. When off, Birth Rate is available. Turning Constant off does not mean that the birth rate varies automatically; the birth rate remains constant unless you animate the Birth Rate parameter.

<Spray>.emitterheight Float default: 25.0 -- animatable, alias: length

The height of the emitter.

<Spray>.emitterwidth Float default: 25.0 -- animatable, alias: width

The width of the emitter.

<Spray>.hideemitter Boolean default: false

When on, the emitter is hidden in the viewports.

Note: The emitter is never rendered.

See also

Particle System Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SuperSpray : GeometryClass

Constructor

superSpray ...

Note: This class is not available in 3D Studio VIZ.

Properties

Basic Parameters

<SuperSpray>.Off_Axis Float default: 0.0 -- animatable, angle

Affects the angle of the particle stream off the Z axis (along the plane of the X axis).

<SuperSpray>.Axis_Spread Float default: 0.0 -- animatable, angle

Affects the spread of the particles away from the emission vector (along the plane of the X axis).

<SuperSpray>.Off_Plane Float default: 0.0 -- animatable, angle

Affects the angle of emission about the Z axis. This has no effect if Off_Axis is set to 0.

<SuperSpray>.Plane_Spread Float default: 0.0 -- animatable, angle

Affects the spread of the particles about the Off_Plane axis. This has no effect if Off_Axis is set to 0.

<SuperSpray>.iconsize Float default: 20.0 -- alias: Emitter_Width

Size of the emitter icon.

<SuperSpray>.iconHidden Boolean default: false

When on, hides the emitter in viewports. When off, the emitter is displayed in viewports. The emitter is never rendered.

<SuperSpray>.viewType Integer default: 0

Set the display icon for particles in the viewport:

0- Dots (Displays the particles as dots.)

1- Ticks (Displays the particles as crosses.)

2- Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.)

3- Bbox (For instanced geometry only, this displays each instanced particle, whether a single object, a hierarchy, or a group, as a bounding box.)

<SuperSpray>.viewPercent Float default: 10.0 -- percentage, alias: Percentage_Displayed

The percentage of particles displayed in the viewport.

Particle Generation

<SuperSpray>.quantityMethod Integer default: 0

Set the method by which the number of particles is determined over time:

0- Use Rate (Specifies a fixed number of particles emitted per frame.)

1- Use Total (Specifies a total number of particles formed over the life of the system.)

Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust, while Use Total is better for bursts of particles over a short period of time.

<SuperSpray>.Birth_Rate Integer default: 10 -- animatable

The number of particles emitted per frame.

<SuperSpray>.Total_Number Integer default: 100

The total number of particles to be emitted.

<SuperSpray>.speed Float default: 10.0 -- animatable

The velocity of the particle at birth, along the normal, in units traveled per frame.

<SuperSpray>.Speed_Variation Float default: 0.0 -- animatable, percentage

Percentage of variation to the speed of emission for each particle.

<SuperSpray>.Emitter_Start Time default: 0f

The frame at which particles begin to exist in the scene.

<SuperSpray>.Emitter_Stop Time default: 30f

The last frame at which particles are emitted.

<SuperSpray>.Display_Until Time default: 100f

Time at which all particles will disappear, regardless of other settings.

<SuperSpray>.life Time default: 30f -- animatable

The lifespan of each particle from the time of creation.

<SuperSpray>.Life_Variation Time default: 0f -- animatable

The number of frames by which the life of each particle can vary from the norm.

<SuperSpray>.subsampleCreationTime Boolean default: false

When on, enables the addition of a time offset to the equations of motion that prevents puffing in time.

<SuperSpray>.subsampleEmitterTranslation Boolean default: true

If the object-based emitter is moving in space, particles are created at integral times at positions along the geometry's path between renderable positions. This prevents puffing in space.

<SuperSpray>.subsampleEmitterRotation Boolean default: true

If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects.

<SuperSpray>.size Float default: 1.0 -- animatable

The target size for all particles in the system.

<SuperSpray>.Size_Variation Float default: 0.0 -- animatable, percentage

The percentage by which the size of each particle may vary from the norm.

<SuperSpray>.Growth_Time Time default: 10f

The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value.

<SuperSpray>.Fade_Time Time default: 10f

The number of intervals over which the particle will shrink to 1/10th its Size setting prior to its death.

<SuperSpray>.seed Integer default: 0 -- alias: Random_Seed

By changing the Seed value, you achieve different results using otherwise identical particle settings.

Particle Type

<SuperSpray>.particleType Integer default: 0

The type of particle emitted:

0- Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra, and so on.)

1- MetaParticles (Uses Metaball particles. These are particle systems in which the individual particles blend together in blobs or streams.)

2- 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:

0- Triangle (Renders each particle as a triangle. Use Triangle particles with noise opacity for steam or smoke.)

1- Cube (Renders each particle as a cube.)

2- 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.)

3- Facing (Renders each particle as a square that always faces the view. Use with an appropriate opacity map for bubbles or snowflakes.)

4- 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.)

5- 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.)

6- SixPoint (Renders each particle as a six-pointed, two-dimensional star.)

7- Sphere (Renders each particle as a sphere.)

<SuperSpray>.Metaparticle_Tension Float default: 1.0 -- animatable

Determines the tightness of the particles, with regard to their tendency to blend with other particles. The higher the Tension, the harder the blobs, and the harder it is for them to merge.

<SuperSpray>.Metaparticle_Tension_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Tension effect.

<SuperSpray>.metaballRenderCoarsness Float default: 0.5 -- alias: Metaparticle_Coarseness

The coarseness for metaparticles in the rendered scene.

<SuperSpray>.metaballViewCoarsness Float default: 1.0

The coarseness for the viewport display.

<SuperSpray>.metaballAutoCoarsness Boolean default: true

When this is on, the rendering coarseness is automatically set, based on the size of the particles, and the viewport coarseness is set to about twice that of the rendering coarseness.

<SuperSpray>.instancingObject Node default: undefined

The object which is instanced.

<SuperSpray>.instanceSubTree Boolean default: false

Turn this on when you want to include the linked children of the picked object in the particle. If the picked object is a group, all children of the group are included.

<SuperSpray>.instanceKeyOffsetType Integer default: 0

Set the animation offset keying:

0- None (Each particle duplicates the timing of the original object. As a result, the animation of all particles will be identically timed.)

1- 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.)

2- Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.)

<SuperSpray>.instanceFrameOffset Integer default: 0 -- alias: Animation_Offset_Amount

The property value is the UI value times the number of ticks per frame. The number of ticks per frame is accessible via the ticksPerFrame system global variable.

<SuperSpray>.mappingType Integer default: 0

Specifies how a mapped material affects the particles:

0- Time (Maps particles over time.)

1- Distance (Maps particles over a distance.)

<SuperSpray>.Mapping_Time_Base Time default: 30f -- animatable

The number of frames from the birth of the particle that it takes to complete one mapping of the particle.

<SuperSpray>.Mapping_Distance_Base Float default: 100.0 -- animatable

The distance, in units, from the birth of the particle that it takes to complete one mapping of the particle.

Rotation and Collision

<SuperSpray>.Spin_Time Time default: 30f -- animatable

The number of frames for one rotation of a particle. If set to 0, no rotation takes place.

<SuperSpray>.Spin_Time_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Spin Time.

<SuperSpray>.Spin_Phase Float default: 0.0 -- animatable, angle

The initial particle rotation, in degrees.

<SuperSpray>.Spin_Phase_Variation Float default: 0.0 -- animatable, percentage

The percent of variation of the Phase.

<SuperSpray>.spinAxisType Integer default: 0

The spin axis for the particles:

0- Random (The spin axis for each of the particles is random.)

1- Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in which they're moving.)

2- User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)

<SuperSpray>.Blur_Stretch Integer default: 0 -- animatable

When greater than 0, the particles stretch along the travel axis, depending on their speed. Specifically, the Stretch value specifies the percent of their length per each unit of the Speed setting (in the Particle Motion group). Thus, if you set Stretch to 2 while Speed is set at 10, the particles are stretched 20 percent longer than their original size along the axis of their travel. This value is only available when you choose Direction of Travel/Mblur.

<SuperSpray>.X_Spin_Vector Float default: 1.0 -- animatable

Spin vector of the X-axis.

<SuperSpray>.Y_Spin_Vector Float default: 0.0 -- animatable

Spin vector of the Y-axis.

<SuperSpray>.Z_Spin_Vector Float default: 0.0 -- animatable

Spin vector of the Z-axis.

<SuperSpray>.Spin_Axis_Variation Float default: 0.0 -- animatable, angle

The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings.

<SuperSpray>.Interparticle_Collisions_On Integer default: 0

Turn on/off interparticle collisions:

0- Off

1- On

<SuperSpray>.Interparticle_Collision_Steps Integer default: 2

The number of intervals per rendering interval, during which an inter-particle collision test is conducted. The higher the value, the more accurate the simulation, but the slower the simulation will run.

<SuperSpray>.Interparticle_Collision_Bounce Float default: 100.0 -- animatable, percentage

The degree to which speed is recovered after a collision.

<SuperSpray>.Interparticle_Collision_Bounce_Variation Float default: 0.0 -- animatable, percentage

The percentage of random variation of the Bounce value, applied to the particles.

Object Motion Inheritance

<SuperSpray>.motionInfluence Float default: 100.0 -- animatable, alias: Object_Motion_Inheritance

The percent of particles that inherit the motion of the object-based emitter at the moment of particle formation.

<SuperSpray>.motionMultiplier Float default: 1.0 -- animatable, alias: Object_Motion_Multiplier

Modifies the amount by which the emitter motion affects the particle motion. This can be a positive or negative number.

<SuperSpray>.motionVariation Float default: 0.0 -- animatable, percentage; alias: Object_Motion_Multiplier_Variation

Percentage of variation of the Multiplier value.

Bubble Motion

<SuperSpray>.Bubble_Amplitude Float default: 0.0 -- animatable

The distance the particle moves off its usual velocity vector as it travels.

<SuperSpray>.Bubble_Amplitude_Variation Float default: 0.0 -- animatable, percentage

The percent of Amplitude variation applied to each particle.

<SuperSpray>.Bubble_Period Time default: 100000f—animatable

The cycle time for one complete oscillation of a particle through the bubble "wave." A recommended value might be 20-30 intervals.

<SuperSpray>.Bubble_Period_Variation Float default: 0.0 -- animatable, percentage

The percent of Period variation for each particle.

<SuperSpray>.Bubble_Phase Float default: 0.0 -- animatable, angle

The initial displacement of the bubble pattern along the vector.

<SuperSpray>.Bubble_Phase_Variation Float default: 0.0 -- animatable, percentage

The percent of Phase variation for each particle.

Particle Spawn

<SuperSpray>.spawnType Integer default: 0

Determines what happens to particles at either collision or death:

0- 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.)

1- Die After Collision (Particles disappear when they strike a deflector to which they're bound, such as the SDeflector.)

2- Spawn on Collision (Spawn effects take place upon collision with a bound deflector.)

3- Spawn on Death (Spawn effects take place at the end of each particle's life.)

4- Spawn Trails (Particles are spawned from existing particles at each frame of that particle's life.)

<SuperSpray>.Die__X_frames_after_collision Time default: 0f -- animatable

The life, in frames, that the particle will persist after the collision. Setting this to 0 (the default) causes particles to vanish immediately after the collision.

<SuperSpray>.Die__X_frames_after_collision_variation Float default: 0.0 -- animatable, percentage

Varies the Persist value of each particle, when Persist is greater than 0. This lets you "feather" the dying off of the particle density.

<SuperSpray>.Spawn_Affects Integer default: 100

The percentage of particles that will spawn. Reducing this reduces the number of particles that produce spawned particles.

<SuperSpray>.Spawn_Multiplier_Variation Float default: 0.0 -- percentage

Percentage range by which the Multiplier value will vary, frame by frame.

<SuperSpray>.Spawn_Direction_Chaos Float default: 0.0 -- animatable, percentage

The amount by which the direction of the spawned particle can vary from the direction of the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned particle to travel in any random direction. A setting of 50 causes the spawned particle to deviate from its parent's path by up to 90 degrees.

<SuperSpray>.Spawn_Speed_Chaos Float default: 0.0 -- animatable

Random percentage range of scaling of the spawned particles relative to their parents, and dependent on the options below.

<SuperSpray>.spawnSpeedType Integer default: 0

Sets the type of speed applied to spawn particles:

0- Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the spawned particles.)

0- Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.)

1- Both (Some particles speed up, while others slow down, based on the .spawn_Speed_Chaos value.)

<SuperSpray>.spawnInheritVelocity Boolean default: false

When on, spawned particles inherit the speed of their parents, in addition to the effect of the .spawn_Speed_Chaos value.

<SuperSpray>.spawnSpeedFixed Boolean default: false

When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range applied randomly to each particle.

<SuperSpray>.Spawn_Scale_Chaos Float default: 0.0 -- animatable

The range of a percentage of change in the speed of the spawned particle relative to its parent. A value of 0 means no change.

<SuperSpray>.spawnScaleType Integer default: 0

The type of speed scaling for the spawned particles:

0- Slow (Applies the speed factor randomly to slow the speed of the spawned particles.)

1- Fast (Randomly speeds up particles based on the speed factor.)

2- 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.

See also

Particle System Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Geometry - NURBS Objects

The following list displays the NURBS objects:

NURBSSurf

Point_Surf


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) and the NURBSSurf class is used typically in object class testing with the classOf() function. Scene objects created as NURBSSurf objects in the 3ds max user interface have the class NURBSSurf.

Constructor

NURBSNode <nurbs_set> ...

See Creating New NURBS Objects for details.

Properties

Properties for NURBSSurf objects are accessed through a NURBSSet descriptor object. See Working with NURBS for more details.

See also

NURBS Node Properties and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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) and the Point_Surf class is used typically in object class testing with the classOf() function. Scene objects created as Point Surface objects in the 3ds max user interface have the class Point_Surf.

Constructor

NURBSNode <nurbs_set> ...

See Creating New NURBS Objects for details.

Properties

<Point_Surf>.thickness Float default: 1.0 -- animatable

Rendered thickness of the surface.

<Point_Surf>.sides Integer default: 12 -- animatable

Rendered sides of the surface.

<Point_Surf>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

Other properties for Point Surfaces are accessed through a NURBSSet descriptor object. See Working with NURBS for more details.

See also

NURBS Node Properties and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Shape : Node

The following list shows the 3ds max shape class objects:

Splines

Arc

Circle

Donut

Ellipse

Helix

Line

NGon

Rectangle

Section

Star

Text

NURBS Curves

CV_Curve

Point_Curve


Shape Common Properties, Operators, and Methods

General Methods

numKnots <shape> [ <spline_index_integer> ]

Returns the number of knots (also known vertices or control points) in the indexed spline as an integer. If the spline index is not specified, returns the number of knots in the entire shape.

For example:

y = donut()

numKnots y

Interpolation Methods

There are a number of interpolation functions that operate on shape scene objects. They provide capabilities such as stepping along a curve within a shape getting coordinates on the curve, getting curve lengths or determining the closest point on a curve to a given coordinate. These are useful for placing cloned objects along a curve or keeping a set of objects in formation near a 'spine' curve as it animates, etc.

The interpolators all take a shape scene object (for example, a line), an optional curve number in case there are several curves in the shape, defaulting to 1, and a parameter in the range 0.0 to 1.0, that specifies a spot on the curve as a proportion along its length. There are two types of interpolator provided:

  • One interpolator matches the 3ds max Path controller in which the percentage along the path is not uniform, but weighted by the vertex spacing. This simple interpolation is interpolating based on parameter space. If a spline has 4 segments, the first segment is parameter values 0-0.25, the second 0.25-0.5, the third 0.5-0.75 and the fourth 0.75-1.0. This is regardless of the length of each segment.

  • Another interpolator that gives you a uniform interpolation along the length of the curve. This interpolation normalizes the parameter space to distance along the length of a spline. So parameter space 0 is the start, 1.0 is the end and 0.5 is halfway along the actual length of the curve.

The non-uniform Path interpolator in 3ds max gives rise to the varying velocity of a path-animated object when the path has unevenly spaced control points. The arc-length interpolators provided here give a uniform placing along the curve no matter how uneven the control point placement. The advantage of the Path interpolator is that it is computationally much more efficient than a uniform arc-length interpolator. The length interpolator uses some caches to speed it up, but you have to help manage them in the way described below.

The optional steps: keyword argument for the methods listed below lets you specify the integration steps. The default steps value is 5 times the curve's 3ds max unit length, which usually is more than enough. For example, if a curve has a length of 100 3ds max units, the default step size would be 500. The interpolation algorithm has an accuracy of no better than + or - (1/steps) 3ds max units. These methods employ a cache to speed up their operation in the common case where you step gradually along a single curve. The cache remembers the state for the last point on the curve and picks up there if you call again on the same curve at the same animation time. This can exponentially speed up interpolation processing. However, MAXScript does not have a way of knowing if you've edited the curve from one call to the next, so you have to be sure to reset the cache with the resetLengthInterp() method if the user can edit the curve between calls in your code.

All coordinates are in the current coordinate system.

pathInterp <shape> [ <curve_num> ] <parameter>

Return a point3 coordinate on the numbered curve (defaults to 1) corresponding to the parameter value (0.0 to 1.0) that matches the 3ds max Path controller percentage (vertex-based) interpolation.

lengthInterp <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]

Return a point3 coordinate on the numbered curve (defaults to 1) corresponding to the parameter value (0.0 to 1.0) that is that fraction along the curve's total length.

resetLengthInterp()

Clear length interpolation cache. Use this if the curve you are length-interpolating along might have been edited between calls.

curveLength <shape> [ <curve_num> ]

Return the arc length of the numbered curve. This length does not reflect any transform level scaling performed on the shape.

pathTangent <shape> [ <curve_num> ] <parameter>

Return the tangent direction vector at the 3ds max Path (vertex-based) interpolated point along the specified curve. You can use this function, for example, to set an object's direction to follow the curve.

lengthTangent <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]

Return the tangent direction vector at the arc-length-interpolated point along the specified curve. You can use this function to set an object's direction to follow the curve.

nearestPathParam <shape> [ <curve_num> ] <point3> [ steps:<integer> ]

Return the interpolation parameter value (0.0 to 1.0) corresponding to the point along the curve that is closest to the given <point3> coordinate. The parameter is given as a 3ds max Path (vertex-based) interpolation parameter value. You can then use pathInterp with this value to find the nearest point's coordinates, or use one of the following functions for converting between arc-length parameters and 3ds max Path percentage parameters.

pathToLengthParam <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]

Return the uniform arc-length length parameter corresponding to the given 3ds max Path (vertex-based) parameter for this curve.

lengthToPathParam <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]

Return the 3ds max Path (vertex-based) parameter corresponding to the given uniform arc-length parameter for this curve.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Shapes - Splines

The following list shows the 3ds max spline shape class objects:

Arc

Circle

Donut

Ellipse

Helix

Line

NGon

Rectangle

Section

Star


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.

Notes

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.

So, looking in the Object Properties dialog, $.renderable=false turns off renderable at the node level. To turn off the spline's renderable property, you need to say $.baseobject.renderable=false.

Methods

The following methods are defined for 3D Studio VIZ.

applyOffset <spline_shape_node> <offset_float>

For each spline in the shape, makes a copy of the spline, offset on all sides to the distance in units specified by offset_float. If a spline is open, the resulting spline and its outline will make a single closed spline. Negative offset_float values create an offset spline to the left of the spline (as the spline is drawn from its start to its finish). The spline_shape_node is converted to a SplineShape (Editable Spline) if it is not already a SplineShape.

measureOffset <spline_shape_node> <point3>

Returns a Float value whose absolute value is the distance from point3 to the closest point on a spline in the shape. The sign of the value is positive if the point3 position is to the left of the spline (as the spline is drawn from its start to its finish). The value returned by this method can usually be used as the offset_float parameter in applyOffset() to have an offset spline pass through the point3 position. If the closest point on a spline in the shape is an endpoint of an open spline, the offset spline will not pass through the point3 position.

trimextend <fixed_node_array> <alterable_node_array> \

[trim: <boolean> ] [extend: <boolean>] [infinite: <boolean>] \

[project: #view | #3D | #grid]

If trim is true (the default), … otherwise … If extend is true (the default), … otherwise … If infinite is false (the default), …, otherwise … Project can be one of the following Name values:

#view (the default) –

#3D –

#grid -

Broken. Document when working.

See also

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Arc : Shape

Constructor

arc ...

Properties

<Arc>.radius Float default: 25.0 -- animatable

The arc radius.

<Arc>.from Float default: 45.0 -- animatable

Location of the start point as an angle measured from the local positive X axis.

<Arc>.to Float default: 135.0 -- animatable

Location of the end point as an angle measured from the local positive X axis.

<Arc>.pie Boolean default: false

When on, creates a closed spline in the form of a pie. The start point and end point are connected to the center with straight segments.

<Arc>.reverse Boolean default: false

When on, the direction of the arc spline is reversed, and the first vertex is placed at the opposite end of an open arc. As long as the shape remains an original shape (and not an editable spline), you can switch its direction by toggling reverse. Once the arc is converted to an editable spline, you can use Reverse at the Spline sub-object level to reverse direction.

<Arc>.steps Integer default: 6

Number of divisions between each vertex.

<Arc>.optimize Boolean default: true

When on, removes unneeded steps from straight segments in the spline.

<Arc>.adaptive Boolean default: false

When on, sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.

<Arc>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<Arc>.thickness Float default: 1.0 -- animatable

Diameter of the rendered spline.

<Arc>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.

<Arc>.viewport_thickness Float default: 1.0

Diameter of the viewport spline.

<Arc>.viewport_sides Integer default: 12

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.

<Arc>.viewport_angle Float default: 0.0

The rotational position of the cross-section in the viewports.

<Arc>.DisplayRenderMesh Boolean default: false

When on, displays the mesh generated by the spline in the viewports.

<Arc>.UseViewportSettings Boolean default: false

When on, displays the mesh generated by the Viewport settings.

<Arc>.DisplayRenderSettings Boolean default: true

When on, displays the mesh generated by the render settings.

<Arc>.renderable Boolean default: true

When on, the spline is displayed in the rendered scene.

<Arc>.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.

Notes

The Reverse property is not accessible to MAXScript in 3ds max 4.

See also

Spline Shape Common Properties, Operators, and Methods

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Circle : Shape

Constructor

circle ...

Properties

<Circle>.radius Float default: 25.0 -- animatable

The radius of the circle.

<Circle>.steps Integer default: 6

The number of divisions between each vertex.

<Circle>.optimize Boolean default: true

When on, removes unneeded steps from straight segments in the spline.

<Circle>.adaptive Boolean default: false

When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.

<Circle>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<Circle>.thickness Float default: 1.0 -- animatable

Diameter of the rendered spline.

<Circle>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.

<Circle>.viewport_thickness Float default: 1.0

Diameter of the viewport spline.

<Circle>.viewport_sides Integer default: 12

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.

<Circle>.viewport_angle Float default: 0.0

The rotational position of the cross-section in the viewports.

<Circle>.DisplayRenderMesh Boolean default: false

When on, displays the mesh generated by the spline in the viewports.

<Circle>.UseViewportSettings Boolean default: false

When on, displays the mesh generated by the Viewport settings.

<Circle>.DisplayRenderSettings Boolean default: true

When on, displays the mesh generated by the render settings.

<Circle>.renderable Boolean default: true

When on, the spline is displayed in the rendered scene.

<Circle>.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

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Donut : Shape

Constructor

donut ...

Properties

<Donut>.radius1 Float default: 35.0 -- animatable

Sets the radius of the first circle.

<Donut>.radius2 Float default: 25.0 -- animatable

Sets the radius of the second circle.

<Donut>.steps Integer default: 6

The number of divisions between each vertex.

<Donut>.optimize Boolean default: true

When on, removes unneeded steps from straight segments in the spline

<Donut>.adaptive Boolean default: false

When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.

<Donut>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<Donut>.thickness Float default: 1.0 -- animatable

Diameter of the rendered spline.

<Donut>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.

<Donut>.viewport_thickness Float default: 1.0

Diameter of the viewport spline.

<Donut>.viewport_sides Integer default: 12

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.

<Donut>.viewport_angle Float default: 0.0

The rotational position of the cross-section in the viewports.

<Donut>.DisplayRenderMesh Boolean default: false

When on, displays the mesh generated by the spline in the viewports.

<Donut>.UseViewportSettings Boolean default: false

When on, displays the mesh generated by the Viewport settings.

<Donut>.DisplayRenderSettings Boolean default: true

When on, displays the mesh generated by the render settings.

<Donut>.renderable Boolean default: true

When on, the spline is displayed in the rendered scene.

<Donut>.mapCoords Boolean default: false

Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also

Spline Shape Common Properties, Operators, and Methods

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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>.renderable Boolean default: true

When on, the spline is displayed in the rendered scene.

<Ellipse>.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

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Helix : Shape

Constructor

helix ...

Properties

<Helix>.radius1 Float default: 35.0 -- animatable

The radius for the Helix start.

<Helix>.radius2 Float default: 15.0 -- animatable

The radius for the Helix end.

<Helix>.height Float default: 25.0 -- animatable

The height of the Helix.

<Helix>.turns Float default: 2.0 -- animatable

The number of turns the Helix makes between its start and end points.

<Helix>.bias Float default: 0.0 -- animatable

Forces the turns to accumulate at one end of the helix. A bias of -1.0 forces the turns towards the start of the helix, a bias of 0.0 evenly distributes the turns between the ends, and a bias of 1.0 forces the turns towards the end of the helix.

<Helix>.direction Integer default: 0

Set the direction the helix turns:

0- Clockwise

1- Counterclockwise

<Helix>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<Helix>.thickness Float default: 1.0 -- animatable

Diameter of the rendered spline.

<Helix>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.

<Helix>.viewport_thickness Float default: 1.0

Diameter of the viewport spline.

<Helix>.viewport_sides Integer default: 12

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.

<Helix>.viewport_angle Float default: 0.0

The rotational position of the cross-section in the viewports.

<Helix>.DisplayRenderMesh Boolean default: false

When on, displays the mesh generated by the spline in the viewports.

<Helix>.UseViewportSettings Boolean default: false

When on, displays the mesh generated by the Viewport settings.

<Helix>.DisplayRenderSettings Boolean default: true

When on, displays the mesh generated by the render settings.

<Helix>.renderable Boolean default: true

When on, the spline is displayed in the rendered scene.

<Helix>.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

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Line : Shape

Constructor

line ...

Properties

<Line>.steps Integer default: 6

The number of divisions between each vertex.

<Line>.optimize Boolean default: true

When on, removes unneeded steps from straight segments in the spline.

<Line>.adaptive Boolean default: false

When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.

<Line>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<Line>.thickness Float default: 1.0 -- animatable

Diameter of the rendered spline.

<Line>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.

<Line>.viewport_thickness Float default: 1.0

Diameter of the viewport spline.

<Line>.viewport_sides Integer default: 12

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.

<Line>.viewport_angle Float default: 0.0

The rotational position of the cross-section in the viewports.

<Line>.DisplayRenderMesh Boolean default: false

When on, displays the mesh generated by the spline in the viewports.

<Line>.UseViewportSettings Boolean default: false

When on, displays the mesh generated by the Viewport settings.

<Line>.DisplayRenderSettings Boolean default: true

When on, displays the mesh generated by the render settings.

<Line>.renderable Boolean default: true

When on, the spline is displayed in the rendered scene.

<Line>.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.

Notes

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 SplineShape : Shape.

See also

Spline Shape Common Properties, Operators, and Methods

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


NGon : Shape

Constructor

ngon ...

Properties

<NGon>.radius Float default: 25.0 -- animatable

The NGon radius.

<NGon>.scribe Integer default: 0

Sets whether the NGon is:

0- Circumscribed (Radius is measured from the center to the sides of the NGon)

1- Inscribed (Radius is measured from the center to the corners of the NGon)

<NGon>.sides Integer default: 6 -- animatable

Number of sides and vertices used by the NGon.

<NGon>.corner_Radius Float default: 0.0 -- animatable

Degree of rounding to apply to the corners of the NGon. A setting of 0 specifies a standard unrounded corner.

<NGon>.circular Boolean default: true -- animatable

When on, specifies a circular NGon.

<NGon>.steps Integer default: 6

The number of divisions between each vertex.

<NGon>.optimize Boolean default: true

When on, removes unneeded steps from straight segments in the spline.

<NGon>.adaptive Boolean default: false

When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.

<NGon>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<NGon>.radius Float default: 1.0 -- animatable

<NGon>.thickness Float default: 1.0 -- animatable

Radius of the rendered spline.

<NGon>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.

<NGon>.viewport_thickness Float default: 1.0

Diameter of the viewport spline.

<NGon>.viewport_sides Integer default: 12

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.

<NGon>.viewport_angle Float default: 0.0

The rotational position of the cross-section in the viewports.

<NGon>.DisplayRenderMesh Boolean default: false

When on, displays the mesh generated by the spline in the viewports.

<NGon>.UseViewportSettings Boolean default: false

When on, displays the mesh generated by the Viewport settings.

<NGon>.DisplayRenderSettings Boolean default: true

When on, displays the mesh generated by the render settings.

<NGon>.renderable Boolean default: true

When on, the spline is displayed in the rendered scene.

<NGon>.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

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Rectangle : Shape

Constructor

rectangle ...

Properties

<Rectangle>.length Float default: 10.0 -- animatable

The size of the rectangle along the local Y axis.

<Rectangle>.width Float default: 25.0 -- animatable

The size of the rectangle along the local X axis.

<Rectangle>.Corner_Radius Float default: 0.0 -- animatable; alias: cornerRadius

Creates rounded corners. When set to 0, the rectangle contains 90-degree corners.

<Rectangle>.steps Integer default: 6

The number of divisions between each vertex.

<Rectangle>.optimize Boolean default: true

When on, removes unneeded steps from straight segments in the spline.

<Rectangle>.adaptive Boolean default: false

When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.

<Rectangle>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<Rectangle>.thickness Float default: 1.0 -- animatable

Radius of the rendered spline.

<Rectangle>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.

<Rectangle>.viewport_thickness Float default: 1.0

Diameter of the viewport spline.

<Rectangle>.viewport_sides Integer default: 12

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.

<Rectangle>.viewport_angle Float default: 0.0

The rotational position of the cross-section in the viewports.

<Rectangle>.DisplayRenderMesh Boolean default: false

When on, displays the mesh generated by the spline in the viewports.

<Rectangle>.UseViewportSettings Boolean default: false

When on, displays the mesh generated by the Viewport settings.

<Rectangle>.DisplayRenderSettings Boolean default: true

When on, displays the mesh generated by the render settings.

<Rectangle>.renderable Boolean default: true

When on, the spline is displayed in the rendered scene.

<Rectangle>.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

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Section : Shape

Constructor

section ...

Properties

<Section>.length Float default: 0.0 -- animatable

The length of the displayed section rectangle.

<Section>.width Float default: 0.0 -- animatable

The width of the displayed section rectangle.

Notes

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

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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>.fillet1 Float default: 0.0

Rounds the inner vertices (the valleys) of the star.

<Star>.fillet2 Float default: 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>.renderable Boolean 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.

Notes

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

See also

Spline Shape Common Properties, Operators, and Methods

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Text : Shape

Constructor

text ...

Properties

<text>.font String default: "Arial"

Choose from a list of all fonts available to 3ds max.

<text>.italic Boolean default: false

Turn on/off italicized text.

<text>.underline Boolean default: false

Turn on/off underlined text.

<text>.alignment Integer default: 1

Sets the alignment of text:

1- Align Left (Aligns text to the left side of its bounding box.)

2- Center (Aligns text to the center of its bounding box.)

3- Align Right (Aligns text to the right side of its bounding box.)

4- Justify (Spaces all lines of text to fill the extents of the bounding box.)

<text>.size Float default: 100.0 -- animatable

Te text height where the height measuring method is defined by the active font.

<text>.kerning Float default: 0.0 -- animatable

The kerning (the distance between letters).

<text>.leading Float default: 0.0 -- animatable

The leading (the distance between lines).

<text>.text String default: "3ds max Text"

The text displayed in the viewport.

<text>.steps Integer default: 6

The number of divisions between each vertex.

<text>.optimize Boolean default: true

When on, removes unneeded steps from straight segments in the spline.

<text>.adaptive Boolean default: false

When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.

<text>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<text>.thickness Float default: 1.0 -- animatable

Radius of the rendered spline.

<text>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.

<text>.viewport_thickness Float default: 1.0

Diameter of the viewport spline.

<text>.viewport_sides Integer default: 12

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.

<text>.viewport_angle Float default: 0.0

The rotational position of the cross-section in the viewports.

<text>.DisplayRenderMesh Boolean default: false

When on, displays the mesh generated by the spline in the viewports.

<text>.UseViewportSettings Boolean default: false

When on, displays the mesh generated by the Viewport settings.

<text>.DisplayRenderSettings Boolean default: true

When on, displays the mesh generated by the render settings.

<text>.renderable Boolean default: true

When on, the spline is displayed in the rendered scene.

<text>.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.

Notes

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

Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Shapes - NURBS Curves

The following list shows the 3ds max NURBS Curves shape class objects:

CV_Curve

Point_Curve


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) and the CV_Curve class is used typically in object class testing with the classOf() function. Scene objects created as CV Curve shape objects in the 3ds max user interface have the class CV_Curve.

Constructor

NURBSNode <nurbs_set> ...

See Creating New NURBS Objects for details.

Properties

<CV_Curve>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<CV_Curve>.thickness Float default: 1.0 -- animatable

Diameter of the rendered curve.

<CV_Curve>.sides Float default: 12.0 -- animatable

Sets the number of sides for the curve mesh in the renderer. A value of 4 will give you a square cross section, for example.

<CV_Curve>.renderable Boolean default: true

When on, the curve is displayed in the rendered scene.

<CV_Curve>.mapCoords Boolean 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 for more details.

See also

Shape Common Properties, Operators, and Methods

NURBS Node Properties and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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) and the Point_Curve class is used typically in object class testing with the classOf() function. Scene objects created as Point Curve shape objects in the 3ds max user interface have the class Point_Curve.

Constructor

NURBSNode <nurbs_set> ...

See Creating New NURBS Objects for details.

Properties

<Point_Curve>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<Point_Curve>.thickness Float default: 1.0 -- animatable

Diameter of the rendered curve.

<Point_Curve>.sides Float default: 12.0 -- animatable

Sets the number of sides for the curve mesh in the renderer. A value of 4 will give you a square cross section, for example.

<Point_Curve>.renderable Boolean default: true

When on, the curve is displayed in the rendered scene.

<Point_Curve>.mapCoords Boolean 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 for more details.

See also

Shape Common Properties, Operators, and Methods

NURBS Node Properties and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Light : Node

The following list shows the 3ds max light class objects:

DirectionalLight

FreeSpot

OmniLight

TargetSpot

TargetDirectionalLight

The following additional light classes are present in 3D Studio VIZ:

Free_Point

Target_Point

See also

Light Common Properties, Operators, and Methods


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. The properties of the Point lights are described in Free Point and Target Point.

<light>.type Name default: #freeDirect

the valid type values are:

#omni

#freeSpot

#targetSpot

#freeDirect

#targetDirect

<light>.enabled Boolean default: true -- alias: on

Turns the light on and off. When on, shading and rendering use the light to illuminate the scene. When off, the light is not used in shading or rendering.

<light>.excludeList Array default: #()

Objects in this array are excluded from the effects of the light.

<light>.includeList Array default: undefined

Objects in this array receive the effects of the light.

<light>.inclExclType Integer default: 3

Select the type of object in the Include/Exclude list:

1- Illumination

2- Shadow Casting

3- Both

<light>.castShadows Boolean default: false

When on, the light will cast shadows on objects.

<light>.rgb Color default: (color 180 180 180) -- animatable, alias: color

The red, green, and blue components of the light's color.

<light>.hsv Point3 default: [0,0,180]

Hue, Saturation, and Value color of light.

<light>.hue Integer default: 0

Hue component of hsv.

<light>.saturation Integer default: 0

Saturation component of hsv.

<light>.value Integer default: 180

Value component of hsv.

<light>.multiplier Float default: 1.0 -- animatable

Amplifies the power of the light by a positive or negative amount.

<light>.contrast Float default: 0.0 -- animatable

Adjusts the contrast between the diffuse and ambient areas of the surface. Leave this set to 0 for normal contrast. Increase the value to increase the contrast for special effects: for example, the harsh light of outer space.

<light>.softenDiffuseEdge Float default: 0.0 -- animatable, alias: Diffuse_Soften

Increasing the value of Soften Diffuse Edge softens the edge between the diffuse and ambient portions of a surface. This helps eliminate edges that can appear on a surface under certain circumstances.

<light>.affectDiffuse Boolean default: true

When on, the light affects the diffuse properties of an object's surface. When off, the light has no effect on the diffuse surface.

<light>.affectSpecular Boolean default: true

When on, the light affects the specular properties of an object's surface. When off, the light has no effect on the specular properties.

<light>.ambientOnly Boolean default: false

When on, the light affects only the ambient component of the illumination.

<light>.projector Boolean default: false

Turn on to project projectorMap.

<light>.projectorMap TextureMap default: undefined

Assigning a TextureMap to projectorMap causes a new subAnim named Projection_Map to be created for the light. This subAnim contains the properties of the TextureMap.

<light>.useShadowProjectorMap Boolean default: false

When on, the light will project a map.

<light>.nearAttenStart Float default: 0.0 -- alias: animatable, alias: Attenuation_Near_Start

The distance at which the light begins to fade in.

<light>.nearAttenEnd Float default: 40.0 -- alias: animatable, alias: Attenuation_Near_End

The distance at which the light reaches its full value.

<light>.useNearAtten Boolean default: false

Enables/Disables near attenuation for the light.

<light>.showNearAtten Boolean default: false

When on, displays the near attenuation range settings in viewports. For spotlights, attenuation ranges appear as lens-shaped sections of the cone. For directional lights, the ranges appear as circular sections of the cone. For omni lights and spot or directional lights with Overshoot turned on, the ranges appear as spheres.

<light>.farAttenStart Float default: 80.0 -- animatable, alias: Attenuation_Far_Start

The distance at which the light begins to fade out.

<light>.farAttenEnd Float default: 200.0 -- animatable, alias: Attenuation_Far_End

The distance at which the light has faded to zero.

<light>.useFarAtten Boolean default: false

Enables/Disables far attenuation for the light.

<light>.showFarAtten Boolean default: false

Displays the far attenuation range settings in viewports. For spotlights, attenuation ranges appear as lens-shaped sections of the cone. For directional lights, the ranges appear as circular sections of the cone. For omni lights and spot or directional lights with Overshoot turned on, the ranges appear as spheres.

<light>.attenDecay Integer default: 1

The type of decay to use:

1- None (Applies no decay. The light maintains full strength from its source to infinity, unless you turn on far attenuation.)

2- 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.)

3- Inverse Square (Applies inverse-square decay. The formula for this is (R0/R)2. This is actually the "real-world" decay of light, but you might find it too dim in the world of computer graphics.)

<light>.DecayRadius Float default: 40.0 -- animatable, alias: Decay_Falloff

The distance over which the decay occurs.

<light>.useGlobalShadowSettings Boolean default: false

Turn on to use global settings for shadows cast by this light. Turn off to enable individual control of the shadows.

<light>.raytracedShadows Boolean default: false

When true, ray traced shadows are produced. When false, shadow-mapped shadows are produced.

<light>.ShadowColor Color default: (color 0 0 0) -- animatable, alias: Shadow_Color

The color of shadows cast by this light.

<light>.shadowMultiplier Float default: 1.0 -- animatable, alias: Shadow_Density

<light>.shadowProjectorMap TextureMap default: undefined

Assigning a TextureMap to shadowProjectorMap causes a new subAnim named Shadow_Projection_Map to be created for the light. This subAnim contains the properties of the TextureMap.

<light>.lightAffectsShadow Boolean default: false

When on, blends the light's color with the shadow color (or shadow colors, if the shadow is mapped).

<light>.atmosShadows Boolean default: true

When on, atmospheric effects cast shadows as the light passes through them.

<light>.atmosOpacity Float default: 100.0 -- animatable, percentage, alias: Atmosphere_Opacity

Adjusts the opacity of the shadows. This value is a percentage.

<light>.atmosColorAmt Float default: 100.0 -- animatable, percentage, alias: Atmosphere_Color_Amount

Adjusts the amount that the atmosphere's color is blended with the shadow color.

If Shadow Maps are being used (raytracedShadows = false), the shadow properties are:

<light>.mapBias Float default: 1.0 -- animatable, alias: map_bias

Moves the shadow toward or away from the shadow-casting object (or objects).

<light>.mapSize Integer default: 512 -- animatable, alias: map_size

Sets the size (in pixels squared) of the shadow map that's computed for the light.

<light>.sampleRange Float default: 4.0 -- animatable, alias: map_range

Determines how much area within the shadow is averaged. This affects how soft the edge of the shadow is.

<light>.absoluteMapBias Boolean default: false -- animatable

When on, the bias for the shadow map is not normalized, but is instead based on a fixed scale expressed in 3ds max units. This value does not change during an animation. You must choose the value, based on the size of the scene extents.

When off, the bias is computed relative to the rest of the scene, and then normalized to 1.0. This provides a common starting bias value in scenes of any size. If the scene extents change, this internal normalization can vary from frame to frame.

<light>.absolute_Bias Integer default: 0 -- integer alias of absoluteMapBias

If Ray Traced Shadows are being used (raytracedShadows = true), the shadow properties are:

<light>.raytraceBias Float default: 0.2 -- animatable

Moves the shadow toward or away from the shadow-casting object (or objects). If the Bias value is too low, shadows can "leak" through places they shouldn't, produce moire patterns or making out-of-place dark areas on meshes. If Bias is too high, shadows can "detach" from an object. If the Bias value is too extreme in either direction, shadows might not be rendered at all.

<light>.maxDepth Integer default: 7 -- animatable

Adjusts the depth of the quadtree used by the raytracer. Greater quadtree depth values can improve ray-tracing time at the cost of memory use. However, there is a depth value where the performance improvement is offset by the time it takes to generate the quadtree itself. This depends on the geometry of the scene.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


DirectionalLight : Light

Constructor

directionalLight ...

Properties

<DirectionalLight>.aspect Float default: 1.0 -- animatable, alias: Aspect_Ratio

The aspect ratio for the rectangular light beam.

<DirectionalLight>.falloff Float default: 45.0 -- animatable

The size of a light's falloff. The Falloff value is measured in 3ds max units.

<DirectionalLight>.showCone Boolean default: false

Turns display of the cone on or off.

<DirectionalLight>.hotspot Float default: 43.0 -- animatable

The size of a light's cone. The Hotspot value is measured in 3ds max units.

<DirectionalLight>.overShoot Boolean default: false

When overshoot is on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone.

<DirectionalLight>.coneShape Integer default: 1 -- alias: lightShape

The shape of the falloff and hotspot areas:

1- Circle

2- Rectangle

See also

Light Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


FreeSpot : Light

Constructor

freeSpot ...

Properties

<Freespot>.aspect Float default: 1.0 -- animatable, alias: Aspect_Ratio

The aspect ratio for the rectangular light beam.

<Freespot>.falloff Float default: 45.0 -- animatable

The angle of a light's falloff. The Falloff value is measured in degrees.

<Freespot>.showCone Boolean default: false

Turns display of the cone on or off.

<Freespot>.hotspot Float default: 43.0 -- animatable

The angle of a light's cone. The Hotspot value is measured in degrees.

<Freespot>.overShoot Boolean default: false

When on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone.

<Freespot>.coneShape Integer default: 1 -- alias: lightShape

The shape of the falloff and hotspot areas:

1- Circle

2- Rectangle

See also

Light Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


OmniLight : Light

Constructor

omniLight ...

Properties

There are no additional properties for OmniLight.

See also

Light Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


TargetDirectionalLight : Light

Constructor

targetDirectionalLight ...

Properties

<TargetDirectionallight>.aspect Float default: 1.0 -- animatable, alias: Aspect_Ratio

The aspect ratio for the rectangular light beam.

<TargetDirectionallight>.falloff Float default: 45.0 -- animatable

The angle of a light's falloff. The Falloff value is measured in degrees.

<TargetDirectionallight>.showCone Boolean default: false

Turns display of the cone on or off.

<TargetDirectionallight>.hotspot Float default: 43.0 -- animatable

The angle of a light's cone. The Hotspot value is measured in degrees.

<TargetDirectionallight>.overShoot Boolean default: false

When on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone.

<TargetDirectionallight>.coneShape Integer default: 1 -- alias: lightShape

The shape of the falloff and hotspot areas:

1- Circle

2- Rectangle

Notes

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

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


TargetSpot : Light

Constructor

targetSpot ...

Properties

<Targetspot>.aspect Float default: 1.0 -- animatable, alias: Aspect_Ratio

The aspect ratio for the rectangular light beam.

<Targetspot>.falloff Float default: 45.0 -- animatable

The angle of a light's falloff. The Falloff value is measured in degrees.

<Targetspot>.showCone Boolean default: false

Turns display of the cone on or off.

<Targetspot>.hotspot Float default: 43.0 -- animatable

The angle of a light's cone. The Hotspot value is measured in degrees.

<Targetspot>.overShoot Boolean default: false

When on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone.

<Targetspot>.coneShape Integer default: 1 -- alias: lightShape

The shape of the falloff and hotspot areas:

1- Circle

2- Rectangle

Notes

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

See also

Light Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Camera : Node

The following list displays the camera objects:

FreeCamera

TargetCamera

See also

Camera Common Properties, Operators, and Methods


Camera Common Properties, Operators, and Methods

Properties

The following properties apply to all camera types:

<camera>.fov Float default: 45.0 -- animatable, angle

Determines how wide an area the camera views.

<camera>.orthoProjection Boolean default: false

When on, the camera view looks just like a User view. When off, the camera view is the standard perspective-like view.

<camera>.type Name default: #free

The type of camera:

#free - Free Camera (Target view can be set in any direction)

#target - Target Camera (Camera will always align view with target object)

<camera>.showCone Boolean default: false

Displays the cone (actually a pyramid) defined by a camera's field of view. The cone appears in the other viewports but does not appear in a camera viewport.

<camera>.showHorizon Boolean default: false

Displays the horizon line. A dark gray line appears at the level of the horizon in the camera's viewport.

<camera>.nearrange Float default: 0.0 -- animatable; alias: Near_Env_Range

The near range for atmospheric effects.

<camera>.farrange Float default: 1000.0 -- animatable; alias: Far_Env_Range

The far range for atmospheric effects.

<camera>.clipManually Boolean default: false

Turn on to define clipping planes. When Clip Manually is off, geometry closer to the camera than 3 units is not displayed.

<camera>.nearclip Float default: 1.0 -- animatable, alias: near_clip

Objects closer than the near clipping plane are invisible to the camera.

<camera>.farclip Float default: 1000.0 -- animatable, alias: far_clip

Objects farther than the far clipping plane are invisible to the camera.

<camera>.showRanges Boolean default: false

When on, displays yellow rectangles within the camera's cone to show the Near and Far range settings.

<camera>.targetDistance Float default: 160.0 -- animatable, alias: Target_Distance

Sets a point to use as an invisible target.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Notes

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)

)

The following script changes the fov of specified camera to simulate a "zoom extents all" for the camera.

Example:

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

(

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

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


TargetCamera : Camera

Constructor

targetCamera ...

Properties

There are no additional properties for TargetCamera.

See also

Camera Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Helper : Node

The following list shows the helper objects:

Standard

Bone

Compass

Dummy

Grid

Point

Protractor

Tape

Atmospheric

BoxGizmo

CylGizmo

SphereGizmo

Camera Match

CamPoint

VRML 1.0/VRBL

Inline

LOD

VRML_VRBL

VRML97

Anchor

AudioClip

Background

Billboard

FogHelper

InlineHelper

LODHelper

NavInfo

ProxSensor

Sound

TouchSensor

TimeSensor

Miscellaneous

LinkOriginPtHelper


Helper - Standard

The following list shows the standard helper objects:

Bone

Compass

Dummy

Grid

Point

Protractor

Tape


Bone : Helper

Constructor

bone ...

Properties

There are no additional properties for Bone.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Notes

The Bone helper object is used by 3ds max to represent the nodes in a Bones system. In 3ds max 4, it is not possible to create a Bones system using IK controllers on the Bones' nodes.

You can create a hierarchy of Bone helper objects which use the standard PRS transform controller for each node. For example:

b0 = bone pos:[x,y,z]

in b0 b1 = bone pos:[x1,y1,z1]

in b1 b2 = bone pos:[x2,y2,z2]

in b2 b3 = bone pos:[x3,y3,z3]

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.

Notes

The Show Compass Rose and Radius properties are not accessible to MAXScript in 3ds max 4.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Dummy, Helper

Dummy : Helper

Constructor

dummy ...

Properties

<Dummy>.boxsize Point3 default: [10,10,10]

Icon size.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Grid : Helper

Constructor

grid ...

Properties

<grid>.length Float default: 50.0 -- animatable

Length of the grid.

<grid>.width Float default: 50.0 -- animatable

Width of the grid.

<grid>.grid Float default: 10.0 -- animatable

The size of the smallest square in the visible grid.

Notes

The Active Color and Display properties are not accessible to MAXScript in 3ds max 4.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Point : Helper

Constructor

point ...

Properties

<Point>.axisLength Float default: 20.0

Sets the length of the tripod axis.

<Point>.size Float default: 20.0 -- animatable

Sets the size of of the point helper.

<Point>.centermarker Boolean default: false -- animatable

When turned on, a small X marker is displayed at the center of the point helper object.

<Point>.axistripod Boolean default: false -- animatable

When this is turned on, an axis tripod with 'x', 'y', and 'z' labels is displayed.

<Point>.cross Boolean default: true -- animatable

When this is turned on, an axis aligned cross is displayed.

<Point>.box Boolean default: false -- animatable

When this is turned on, a square box is displayed centered at the center of the point helper object.

<Point>.constantscreensize Boolean default: false -- animatable

When this is turned on, the point object remains the same size in screen space regardless of how much the user zooms in or out.

<Point>.drawontop Boolean default: false -- animatable

When this is on, the point helper object draws lines with the Z buffer turned off (which usually causes it to appear in front of other objects).

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Protractor : Helper

Constructor

protractor ...

Properties

There are no additional properties for Protractor.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Tape : Helper

Constructor

tape ...

Properties

<Tape>.length Float default: 50.0 -- animatable

Length of the tape object.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Notes

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

CylGizmo

SphereGizmo


BoxGizmo : Helper

Constructor

boxGizmo ...

Properties

<BoxGizmo>.length Float default: 0.0 -- animatable

Length of the box gizmo.

<BoxGizmo>.width Float default: 0.0 -- animatable

Width of the box gizmo.

<BoxGizmo>.height Float default: 0.0 -- animatable

Height of the box gizmo.

<BoxGizmo>.seed Integer default: 0 -- alias: parameter

Base value used to generate the atmospheric effect. Each apparatus in the scene should have a different seed. If more than one apparatus uses the same seed and same atmospheric effect, they will produce nearly identical results.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


CylGizmo : Helper

Constructor

cylGizmo ...

Properties

<CylGizmo>.radius Float default: 0.0 -- animatable

Radius of cylinder gizmo object.

<CylGizmo>.height Float default: 0.0 -- animatable

Height of cylinder gizmo object.

<CylGizmo>.seed Integer default: 0 -- alias: parameter

Base value used to generate the atmospheric effect. Each apparatus in the scene should have a different seed. If more than one apparatus uses the same seed and same atmospheric effect, they will produce nearly identical results.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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:

0- Off

1- 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.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Helper - Camera Match

The following list shows the camera match helper objects:

CamPoint


CamPoint : Helper

Constructor

camPoint ...

Properties

<CamPoint>.showAxis Boolean default: true

When on, an axis tripod is displayed with the camera point object.

<CamPoint>.axisLength Float default: 20.0

The length of the axis tripod.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Helper - VRML 1.0/VRBL

The following list shows the VRML 1.0/VRBL helper objects:

Inline

LOD

VRML_VRBL


Inline : Helper

Constructor

inline ...

Properties

There are no additional properties for Inline.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


LOD : Helper

Constructor

lod ...

Properties

There are no additional properties for LOD.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


VRML_VRBL : Helper

Constructor

vrml_vrbl ...

Properties

There are no additional properties for VRML_VRBL.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Helper - VRML97

The following list shows the VRML97 helper objects:

Anchor

AudioClip

Background

Billboard

FogHelper

InlineHelper

LODHelper

NavInfo

ProxSensor

Sound

TouchSensor

TimeSensor


Anchor : Helper

Constructor

anchor ...

Properties

There are no additional properties for Anchor.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


AudioClip : Helper

Constructor

audioClip ...

Properties

There are no additional properties for AudioClip.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Background : Helper

Constructor

background ...

Properties

There are no additional properties for Background.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Billboard : Helper

Constructor

billboard ...

Properties

There are no additional properties for Billboard.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


FogHelper : Helper

Constructor

fogHelper ...

Properties

There are no additional properties for FogHelper.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


InlineHelper : Helper

Constructor

inlineHelper ...

Properties

There are no additional properties for InlineHelper.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


LODHelper : Helper

Constructor

lodHelper ...

Properties

There are no additional properties for LODHelper.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


NavInfo : Helper

Constructor

navInfo ...

Properties

There are no additional properties for NavInfo.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


ProxSensor : Helper

Constructor

proxSensor ...

Properties

There are no additional properties for ProxSensor.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Sound : Helper

Constructor

sound ...

Properties

There are no additional properties for Sound.

Variables

WAVsound.filename

Get/set Sound track filename as <string>. There currently is not a way to perform and Remove Sound via MAXScript

WAVsound.start

Get/set Sound track range start time as <time>.

WAVsound.end

A read only variable to get the Sound track range end time as a <time> value.

WAVsound.mute

Get/set whether Sound track is active as <boolean>.

WAVsound.isPlaying

A read only variable that returns whether the Sound track is currently playing as a <boolean> value.

Methods

WAVsound.scrub <interval>

Plays back the specified time interval of the Sound track.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


TimeSensor : Helper

Constructor

timeSensor ...

Properties

There are no additional properties for TimeSensor.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


TouchSensor : Helper

Constructor

touchSensor ...

Properties

There are no additional properties for TouchSensor.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

Sunlight

RingArray

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 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 IK_ControllerMatrix3Controller : Matrix3Controller.


Sunlight : System

Sunlight system objects are not creatable by MAXScript.

A Sunlight system is comprised of a Compass Helper object and a TargetDirectionalLight 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


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 object, a variable number of Box 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 Slave_Controller : Matrix3Controller.


SpacewarpObject : Node

Note: Spacewarp objects are not available in 3D Studio VIZ.

The following list shows the space warp objects:

Geometric/Deformable

Bomb

Conform

SpaceDisplace

SpaceFFDBox

SpaceFFDCyl

SpaceRipple

SpaceWave

Particles and Dynamics

Gravity

Motor

PBomb

Push

Wind

Modifier-Based

SpaceBend

SpaceNoise

SpaceSkew

SpaceStretch

SpaceTaper

SpaceTwist

Dynamics Interface

PDynaFlect

SDynaFlect

UDynaFlect

Particles Only

Deflector

Path_Follow

POmniFlect

SDeflector

SOmniFlect

UDeflector

UOmniFlect


Spacewarp - Geometric/Deformable

Note: Spacewarp objects are not available in 3D Studio VIZ.

The following list shows the geometric/deformable space warp objects:

Bomb

Conform

SpaceDisplace

SpaceFFDBox

SpaceFFDCyl

SpaceRipple

SpaceWave


Bomb : SpacewarpObject

Constructor

bomb ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Bomb>.strength Float default: 1.0 -- animatable

The power of the bomb. Larger values make the particles fly farther. The closer an object is to the bomb, the greater the effect of the bomb.

<Bomb>.spin Float default: 0.0 -- animatable

The rate at which fragments rotate, in revolutions per second.

<Bomb>.falloff Float default: 100.0 -- animatable

The distance from the bomb, in world units, of the effect of the bomb. Fragments past this distance are not affected by the Strength and Spin settings, but are affected by the Gravity setting.

<Bomb>.fallOffEnable Boolean default: false

Turn on to use the Falloff setting. The falloff range appears as a yellow, tri-hooped sphere.

<Bomb>.minFragmentSize Integer default: 1

The minimum number of faces per fragment to be randomly generated by the "explosion."

<Bomb>.maxFragmentSize Integer default: 1

The maximum number of faces per fragment to be randomly generated by the "explosion."

<Bomb>.Gravity Float default: 1.0 -- animatable

The acceleration due to gravity. Note that gravity is always in the direction of the world Z axis. You can have negative gravity.

<Bomb>.chaos Float default: 0.0 -- animatable

Adds random variation to the explosion to make it less uniform. A setting of 0.0 is totally uniform; 1.0 is a realistic setting. A value greater than 1.0 makes the explosion extra chaotic.

<Bomb>.detonation Time default: 5f

The frame at which the bomb goes off. Bound objects are unaffected before this time.

<Bomb>.seed Integer default: 0

Change to alter randomly generated numbers in the bomb. You can achieve a different bomb effect by changing Seed while maintaining the other settings.

Associated Methods

bindSpaceWarp <node> <bomb_node>

Associated Binding Modifier

BombBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


ConformSpaceWarp : SpacewarpObject

Constructor

conformSpaceWarp ...

Note: This class is not available in 3D Studio VIZ.

Properties

<ConformSpaceWarp>.Projection_Distance Float default: 0.0 -- animatable

The distance a vertex in the bound object moves from its original location if it does not intersect the target object.

<ConformSpaceWarp>.Standoff_Distance Float default: 1.0 -- animatable

The distance maintained between the vertex and the surface of the target object.

<ConformSpaceWarp>.Selected_Verts Integer default: 0 -- animatable

When on, only the sub-object selection of vertices on the Stack are pushed. When off, all vertices in the object are pushed regardless of the Stack selection:

0- Off

1- On

<ConformSpaceWarp>.Icon_Size Float default: 0.0

The size of the icon.

Notes

There is not a way to set the Wrap To Object using MAXScript in 3ds max 4.

Associated Methods

bindSpaceWarp <node> <conformSpaceWarp_node>

Associated Binding Modifier

SpaceConform

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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:

0- Planar (Projects the map from a single plane.)

1- Cylindrical (Projects the map as if it were wrapped around the cylinder.)

2- 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.)

3- Shrink Wrap (Truncates the corners of the map and joins them all at a single pole, creating one singularity.)

<Spacedisplace>.length Float default: 1.0 -- animatable

The length of the bounding box on the space warp gizmo.

<Spacedisplace>.width Float default: 1.0 -- animatable

The width of the bounding box on the space warp gizmo.

<Spacedisplace>.height Float default: 1.0 -- animatable

The height of the bounding box on the space warp gizmo.

<Spacedisplace>.U_Flip Boolean default: false

When on, reverses the orientation of the map along the U-axis.

<Spacedisplace>.U_Tile Float default: 1.0 -- animatable

The number of times the map repeats along the U-axis.

<Spacedisplace>.V_Flip Boolean default: false

When on, reverses the orientation of the map along the V-axis.

<Spacedisplace>.V_Tile Float default: 1.0 -- animatable

The number of times the map repeats along the U-axis.

<Spacedisplace>.W_Flip Boolean default: false

When on, reverses the orientation of the map along the W-axis.

<Spacedisplace>.W_Tile Float default: 1.0 -- animatable

The number of times the map repeats along the U-axis.

The following properties are defined for SpaceDisplace, but are not used:

<Spacedisplace>.axis Integer default: 0

<Spacedisplace>.cap Boolean default: false

<Spacedisplace>.useMap Boolean default: false

<Spacedisplace>.applyMap Boolean default: false

Associated Methods

bindSpaceWarp <node> <spaceDisplace_node>

Associated Binding Modifier

DisplaceBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SpaceFFDBox : SpacewarpObject

Constructor

spaceFFDBox ...

Note: This class is not available in 3D Studio VIZ.

Properties

<SpaceFFDBox>.length Float default: 0.0 -- animatable

Sets the length of the lattice.

<SpaceFFDBox>.width Float default: 0.0 -- animatable

Sets the width of the lattice.

<SpaceFFDBox>.height Float default: 0.0 -- animatable

Sets the length of the lattice.

<SpaceFFDBox>.dispLattice Boolean default: true -- alias: Lattice

When turned on, lines are drawn connecting the control points to make a grid.

<SpaceFFDBox>.dispSource Boolean default: false -- alias: Source_Volume

When on, the control points and lattice are displayed in their unmodified state.

<SpaceFFDBox>.deformType Integer default: 0

Specifies which vertices are affected by the FFD:

0- Only In Volume (Only vertices that lie inside the source volume are deformed. Vertices outside the source volume are not affected.)

1- All Vertices (All vertices are deformed regardless of whether they lie inside or outside the source volume, depending on the .falloff value.)

<SpaceFFDBox>.falloff Float default: 0.0 -- animatable

The distance from the lattice that the FFD effect will decrease to zero. When this value is set to 0, it's effectively turned off, and there is no falloff; that is, all vertices are affected regardless of their distance from the lattice. The units of the Falloff parameter are specified relative to the size of the lattice: A falloff of 1 means that the effect will go to 0 for points that are a lattice width/length/height away from the lattice (depending on which side they are on).

<SpaceFFDBox>.tension Float default: 25.0 -- animatable

Sets the tension of the deformation splines.

<SpaceFFDBox>.continuity Float default: 25.0 -- animatable

Sets the continuity of the deformation splines.

Associated Methods

bindSpaceWarp <node> <spaceFFDBox_node>

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.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

See also Class and Object Inspector Functions and Scripting Vertex and Control Point Animation for details on accessing the control points in an FFD.


SpaceFFDCyl : SpacewarpObject

Constructor

spaceFFDCyl ...

Note: This class is not available in 3D Studio VIZ.

Properties

<SpaceFFDCyl>.radius Float default: 0.0 -- animatable

Sets the radius of the lattice.

<SpaceFFDCyl>.height Float default: 0.0 -- animatable

Sets the height of the lattice.

<SpaceFFDCyl>.dispLattice Boolean default: true -- alias: Lattice

When on, lines are drawn connecting the control points to make a grid.

<SpaceFFDCyl>.dispSource Boolean default: false -- alias: Source_Volume

When on, the control points and lattice are displayed in their unmodified state.

<SpaceFFDCyl>.deformType Integer default: 0

Specifies which vertices are affected by the FFD:

0- Only In Volume (Only vertices that lie inside the source volume are deformed. Vertices outside the source volume are not affected.)

1- All Vertices (All vertices are deformed regardless of whether they lie inside or outside the source volume, depending on the .falloff value.)

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

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

See also Class and Object Inspector Functions and Scripting Vertex and Control Point Animation for details on accessing the control points in an FFD.


SpaceRipple : SpacewarpObject

Constructor

spaceRipple ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Spaceripple>.amplitude1 Float default: 5.0 -- animatable, alias: Amplitude_1

Ripple amplitude along the ripple warp object's local X axis. Amplitude is expressed in active units.

<Spaceripple>.amplitude2 Float default: 5.0 -- animatable, alias: Amplitude_2

Ripple amplitude along the ripple warp object's local Y axis. Amplitude is expressed in active units.

<Spaceripple>.wavelength Float default: 25.0 -- animatable, alias: Wave_Length

The length of each wave, in active units.

<Spaceripple>.phase Float default: 0.0 -- animatable

Offsets the phase of the wave from its origin at the ripple object's center. Whole values have no effect; only fractional values do. Animating this parameter makes the ripple appear to travel through space.

<Spaceripple>.decay Float default: 0.0 -- animatable

When set to 0.0, the ripple has the same amplitude or amplitudes throughout world space. Increasing the Decay value causes amplitude to diminish as distance increases from the position of the ripple warp object.

<Spaceripple>.circles Integer default: 10

The number of circles in the ripple icon.

<Spaceripple>.segments Integer default: 16

The number of segments (pie slices) in the ripple icon.

<Spaceripple>.divisions Integer default: 4

Adjusts the size of the ripple icon without altering the ripple effect as scaling would.

Associated Methods

bindSpaceWarp <node> <spaceRipple_node>

Associated Binding Modifier and Properties

RippleBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. The following property is associated with this binding modifier:

<RippleBinding>.Flexibility Float default: 1.0

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

Motor

PBomb

Push

Wind


Gravity : SpacewarpObject

Constructor

gravity ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Gravity>.strength Float default: 1.0 -- animatable

Increasing Strength increases the effect of gravity; that is, how objects move in relation to the Gravity icon's direction arrow. Strength less than 0.0 creates negative gravity, which repels particles moving in the same direction and attracts particles moving in the opposite direction. When Strength is set to 0.0, the Gravity space warp has no effect.

<Gravity>.decay Float default: 1.0 -- animatable

When Decay is set to 0.0, the Gravity space warp has the same strength throughout world space. Increasing the Decay value causes gravity strength to diminish as distance increases from the position of the gravity warp object.

<Gravity>.gravitytype Integer default: 0

Set the type of gravity effect:

0– Planar

1- Spherical

<Gravity>.showRange Boolean default: 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.

<Gravity>.iconsize Float default: 10.0 -- animatable

Size of the Gravity warp object icon, in active units. You set the initial size when you drag to create the Gravity object. This value does not change the gravity effect.

<Gravity>.hoopson Boolean default: true

When on, and when the decay value is greater than 0.0, icons in the viewports indicate the range at which the force of gravity is half the maximum value. For the Planar option, the indicators are two planes; for use the Spherical option, the indicator is a double-hooped sphere.

Associated Methods

bindSpaceWarp <node> <gravity_node>

Associated Binding Modifier

GravityBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Motor, SpacewarpObject

Motor : SpacewarpObject

Constructor

motor ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Motor>.On_Time Time default: 0f

The frame at which the motor effect begins.

<Motor>.Off_Time Time default: 30f

The frame at which the motor effect ends.

<Motor>.Basic_Torque Float default: 1.0 -- animatable

The amount of force exerted by the space warp.

<Motor>.units Integer default: 0

The unit of measure for the basic torque setting:

0- Newton-meters

1- Pound-feet

2- Pound-inches

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

0- Off

1- On

<Motor>.Reversible Integer default: 0

When on, if the object's speed exceeds the Target Speed setting, the force is reversed:

0- Off

1- 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:

0- RPH

1- RPM

2- 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:

0- Off

1- On

<Motor>.Variation_Period_1 Time default: 0.625f

The time over which the noise variation makes a full cycle.

<Motor>.Amplitude_1 Float default: 100.0 -- animatable

The strength of the variation (in percent).

<Motor>.Variation_Phase_1 Float default: 0.0 -- animatable, angle

Offsets the variation pattern.

<Motor>.Variation_Period_2 Time default: 0.625f

Provides an additional variation pattern to increase the noise.

<Motor>.Amplitude_2 Float default: 100.0 -- animatable

The strength of the variation of the second wave in (percent).

<Motor>.Variation_Phase_2 Float default: 0.0 -- animatable, angle

Offsets the variation pattern of the second wave.

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

0- Off

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


PBomb : SpacewarpObject

Constructor

pbomb ...

Note: This class is not available in 3D Studio VIZ.

Properties

<PBomb>.symmetry Integer default: 0

The shape, or pattern of the blast effect:

0- Spherical (The blast force radiates outward from the PBomb icon in all directions. The icon looks like a spherical anarchist's bomb.)

1- 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.)

2- 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>.chaos Float default: 10.0 -- percentage

The blast forces vary for each particle or each frame, an effect similar to Brownian motion, with a rate of change in the direction of force equal to the rendering interval rate.

<PBomb>.Start_Time Time default: 30f

The frame number at which the impulse forces are first applied to the particles.

<PBomb>.Lasts_For Time default: 1f

The number of frames, beyond the first, over which the forces are applied. This value should typically be a small number, such as between 0 and 3.

<PBomb>.strength Float default: 1.0 -- animatable

The change in velocity along the blast vector, in units per frame. Increasing Strength increases the speed with which the particles are blown away from the bomb icon.

<PBomb>.Decay_Type Integer default: 1

Sets the decay type:

0- 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.)

1- Linear (The impulse forces decay linearly between the full Strength setting to a value of 0 at the specified Range setting.)

2- Exponential (The impulse forces decay exponentially between the full Strength setting to a value of 0 at the specified Range setting.)

<PBomb>.range Float default: 1000.0 -- animatable

The maximum distance, in units, over which the PBomb icon affects the bound particle system. If the Range is large enough to reach only a portion of the particle system, only that part of the system is affected.

<PBomb>.Icon_Size Float default: 0.0

The overall size of the PBomb icon.

Associated Methods

bindSpaceWarp <node> <pbomb_node>

Associated Binding Modifier

PBombMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


PushSpaceWarp : SpacewarpObject

Constructor

pushSpaceWarp ...

Note: This class is not available in 3D Studio VIZ.

Properties

<PushSpaceWarp>.On_Time Time default: 0f

The frame in which the space warp begins its effect.

<PushSpaceWarp>.Off_Time Time default: 30f

The frame in which the space warp ends its effect.

<PushSpaceWarp>.Basic_Force Float default: 1.0 -- animatable

The amount of force exerted by the space warp.

<PushSpaceWarp>.units Integer default: 0

The unit of force used by the basic force:

0- Newtons

1- Pounds

<PushSpaceWarp>.Feedback_On Integer default: 0

When on, the force varies depending on the speed of the affected objects relative to the specified Target Speed. When off, the force remains constant, regardless of the speed of the affected objects:

0- Off

1- On

<PushSpaceWarp>.Reversible Integer default: 0

When on, if the object's speed exceeds the Target Speed setting, the force is reversed

0- Off

1- On

<PushSpaceWarp>.Target_Speed Float default: 100.0 -- animatable

The maximum speed in units per frame before the Feedback takes effect.

<PushSpaceWarp>.Control_Gain Float default: 50.0 -- animatable

Specifies how quickly the force adjusts to approaching the target speed. If set to 100 percent, the correction is immediate. If set lower, a slower and "looser" response occurs.

<PushSpaceWarp>.Enable_Variation Integer default: 0

Turn on/off variations:

0- Off

1- On

<PushSpaceWarp>.Variation_Period_1 Time default: 0.625f—animatable

The time over which the noise variation makes a full cycle.

<PushSpaceWarp>.Amplitude_1 Float default: 100.0 -- animatable

The strength of the variation (in percent).

<PushSpaceWarp>.Variation_Phase_1 Float default: 0.0 -- animatable, angle

Offsets the variation pattern.

<PushSpaceWarp>.Variation_Period_2 Time default: 0.625f—animatable

Provides an additional variation pattern (a second wave) to increase the noise.

<PushSpaceWarp>.Amplitude_2 Float default: 100.0 -- animatable

The strength of the variation of the second wave (in percent).

<PushSpaceWarp>.Variation_Phase_2 Float default: 0.0 -- animatable, angle

Offsets the variation pattern of the second wave

<PushSpaceWarp>.Range_Enable Integer default: 0

When on, limits the range of the effect to a sphere, displayed as a tri-hooped sphere. The effect falls off increasingly as the particles near the boundary of the sphere.

0- Off

1- On

<PushSpaceWarp>.Range_Value Float default: 1000.0 -- animatable

The radius of the range of the effect, in units.

<PushSpaceWarp>.Icon_Size Float default: 0.0

The size of the Push icon. This is for display purposes only, and does not alter the Push effect.

Associated Methods

bindSpaceWarp <node> <pushSpaceWarp_node>

Associated Binding Modifier

PushMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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:

0- Planar

1- 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.

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Spacewarp - Modifier-Based

Note: Spacewarp objects are not available in 3D Studio VIZ.

The following list shows the Modifier-Based space warp objects:

SpaceBend

SpaceNoise

SpaceSkew

SpaceStretch

SpaceTaper

SpaceTwist


SpaceBend : SpacewarpObject

Constructor

spaceBend ...

Note: This class is not available in 3D Studio VIZ.

Properties

<SpaceBend>.length Float default: 0.0 -- animatable

The length of the warp object.

<SpaceBend>.width Float default: 0.0 -- animatable

The width of the warp object.

<SpaceBend>.height Float default: 0.0 -- animatable

The height of the warp object.

<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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SpaceNoise : SpacewarpObject

Constructor

spaceNoise ...

Note: This class is not available in 3D Studio VIZ.

Properties

<SpaceNoise>.length Float default: 0.0 -- animatable

The length of the warp object.

<SpaceNoise>.width Float default: 0.0 -- animatable

The width of the warp object.

<SpaceNoise>.height Float default: 0.0 -- animatable

The height of the warp object.

<SpaceNoise>.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:

0- Off

1- 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.

Notes

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.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SpaceSkew : SpacewarpObject

Constructor

spaceSkew ...

Note: This class is not available in 3D Studio VIZ.

Properties

<SpaceSkew>.length Float default: 0.0 -- animatable

The length of the warp object.

<SpaceSkew>.width Float default: 0.0 -- animatable

The width of the warp object.

<SpaceSkew>.height Float default: 0.0 -- animatable

The height of the warp object.

<SpaceSkew>.decay Float default: 0.0 -- animatable

When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially.

<SpaceSkew>.amount Float default: 0.0 -- animatable

The angle to skew from the vertical plane.

<SpaceSkew>.direction Float default: 0.0 -- animatable

The direction of the skew relative to the horizontal plane.

<SpaceSkew>.Lower_Limit Float default: 0.0 -- animatable

The lower limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry.

<SpaceSkew>.Upper_Limit Float default: 0.0 -- animatable

The upper limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry.

Associated Methods

bindSpaceWarp <node> <spaceSkew_node>

Associated Binding Modifier

SimpleOSMToWSMMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SpaceStretch : SpacewarpObject

Constructor

spaceStretch ...

Note: This class is not available in 3D Studio VIZ.

Properties

<SpaceStretch>.length Float default: 0.0 -- animatable

The length of the warp object.

<SpaceStretch>.width Float default: 0.0 -- animatable

The width of the warp object.

<SpaceStretch>.height Float default: 0.0 -- animatable

The height of the warp object.

<SpaceStretch>.decay Float default: 0.0 -- animatable

When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially.

<SpaceStretch>.Stretch Float default: 0.0 -- animatable

The base scale factor for all three axes. The scale factor derived from the Stretch value varies according to the sign of the value:

Positive stretch values define a scale factor equal to Stretch+1. For example, a stretch value of 1.5 yields a scale factor of 1.5+1=2.5, or 250 percent.

Negative stretch values define a scale factor equal to -1/(Stretch-1). For example, a stretch value of -1.5 yields a scale factor of -1/(-1.5-1)=0.4, or 40 percent.

<SpaceStretch>.Amplify Float default: 0.0 -- animatable

The scale factor applied to the minor axes. Amplify generates a multiplier using the same technique as stretch. The multiplier is then applied to the Stretch value before the scale factor for the minor axes is calculated.

<SpaceStretch>.from Float default: 0.0 -- animatable

The boundary of the stretch effect along the negative Stretch Axis. The Lower Limit can be 0 or any negative number.

<SpaceStretch>.to Float default: 0.0 -- animatable

The boundary of the stretch effect along the positive Stretch Axis. The Upper Limit can be 0 or any positive number.

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SpaceTaper : SpacewarpObject

Constructor

spaceTaper ...

Note: This class is not available in 3D Studio VIZ.

Properties

<SpaceTaper>.length Float default: 0.0 -- animatable

The length of the warp object.

<SpaceTaper>.width Float default: 0.0 -- animatable

The width of the warp object.

<SpaceTaper>.height Float default: 0.0 -- animatable

The height of the warp object.

<SpaceTaper>.decay Float default: 0.0 -- animatable

When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially.

<SpaceTaper>.amount Float default: 0.0 -- animatable

The extent to which the ends are scaled. Amount is a relative value with a maximum of 10.

<SpaceTaper>.curvature Float default: 0.0 -- animatable

Applies a curvature to the sides of the Taper gizmo, thus affecting the shape of the tapered object. Positive values produce an outward curve along the tapered sides, negative values an inward curve. At 0, the sides are unchanged.

<SpaceTaper>.symmetry Integer default: 0

When on, produces a symmetrical taper around the primary axis. A taper is always symmetrical around the effect axis:

0- Off

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SpaceTwist : SpacewarpObject

Constructor

spaceTwist ...

Note: This class is not available in 3D Studio VIZ.

Properties

<SpaceTwist>.length Float default: 0.0 -- animatable

The length of the warp object.

<SpaceTwist>.width Float default: 0.0 -- animatable

The width of the warp object.

<SpaceTwist>.height Float default: 0.0 -- animatable

The height of the warp object.

<SpaceTwist>.decay Float default: 0.0 -- animatable

When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially.

<SpaceTwist>.angle Float default: 0.0 -- animatable

The amount of twist around the vertical axis.

<SpaceTwist>.bias Float default: 0.0 -- animatable

Causes the twist rotation to bunch up at either end of the object. When the parameter is negative, the object twists closer to the gizmo center. When the value is positive, the object twists more away from the gizmo center. When the parameter is 0, the twisting is uniform.

<SpaceTwist>.Lower_Limit Float default: 0.0 -- animatable

The lower limit for the twist effect.

<SpaceTwist>.Upper_Limit Float default: 0.0 -- animatable

The upper limit for the twist effect.

Associated Methods

bindSpaceWarp <node> <spaceTwist_node>

Associated Binding Modifier

SimpleOSMToWSMMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Spacewarp - Dynamics Interface

Note: Spacewarp objects are not available in 3D Studio VIZ.

The following list shows the Modifier-Based space warp objects:

PDynaFlect

SDynaFlect

UDynaFlect


PDynaFlect : SpacewarpObject

Constructor

PDynaFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties

<PDynaFlect>.Time_On Time default: 0f

Specifies the frame at which the deflection begins.

<PDynaFlect>.Time_Off Time default: 100f -- animatable

Specifies the frame at which the deflection ends.

<PDynaFlect>.Reflects Float default: 10000.0 -- animatable

Specifies the percentage of particles to be reflected by the PDynaFlect.

<PDynaFlect>.bounce Float default: 1.0 -- animatable

This multiplier specifies how much of the initial speed of the particle is maintained after collision with the PDynaFlect.

<PDynaFlect>.Bounce_Variation Float default: 0.0 -- animatable

Specifies the variation of Bounce applied to the range of particles.

<PDynaFlect>.chaos Float default: 0.0 -- animatable

Applies a random variation to the bounce angle.

<PDynaFlect>.Velocity_Inheritance Float default: 1.0 -- animatable

Determines how much of a moving PDynaFlect's speed is applied to reflected or refracted particles.

<PDynaFlect>.Particle_Mass Float default: 1.0 -- animatable

Specifies the mass based on the chosen unit.

<PDynaFlect>.Particle_Mass_Units Integer default: 0

Sets the mass unit for particles:

0- Gram

1- Kilogram

2- Pound

<PDynaFlect>.width Float default: 0.0 -- animatable

Specify the width of the PDynaFlect icon. This is for display purposes only and does not influence the deflector effect.

<PDynaFlect>.height Float default: 0.0 -- animatable

Specify the height of the PDynaFlect icon. This is for display purposes only and does not influence the deflector effect.

Associated Methods

bindSpaceWarp <node> <PDynaFlect_node>

Associated Binding Modifier

PDynaFlectMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SDynaFlect : SpacewarpObject

Constructor

SDynaFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties

<SDynaFlect>.'time on' Integer default: 0 -- animatable; alias: time_on

The time at which the deflection begins.

<SDynaFlect>.'time off' Integer default: 16000 -- animatable; alias: time_off

The time at which the deflection ends.

<SDynaFlect>.affects Float default: 10000.0 -- animatable; percentage; alias: reflects

The percentage of particles to be reflected by the PDynaFlect.

<SDynaFlect>.bouncevar Float default: 0.0 -- animatable; percentage; alias: bounce_variation

The variation of Bounce applied to the range of particles.

<SDynaFlect>.inheritVelocity Float default: 1.0 -- animatable: alias: velocity_inheritance

Determines how much of a moving PDynaFlect's speed is applied to reflected or refracted particles.

<SDynaFlect>.mass Float default: 1.0 -- animatable; alias: particle_mass

The mass based on the chosen unit.

<SDynaFlect>.'mass units' Integer default: 0 -- animatable; alias: particle_mass_units

The unit to use for particle mass values:

0- Gram

1- Kilogram

2- Pound

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

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


UDynaFlect : SpacewarpObject

Constructor

UDynaFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties

<UDynaFlect>.'time on' Integer default: 0 -- animatable; alias: time_on

Time at which the deflector turns on.

<UDynaFlect>.'time off' Integer default: 1600000 -- animatable; alias: time_off

Time at which the deflector turns off.

<UDynaFlect>.affects Float default: 10000.0 -- animatable; percentage; alias: reflects

The percentage of particles to be reflected by the UDynaFlect.

<UDynaFlect>.bounce Float default: 1.0 -- animatable

This multiplier specifies how much of the initial speed of the particle is maintained after collision with the UDynaFlect.

<UDynaFlect>.bouncevar Float default: 0.0 -- animatable; percentage; alias: bounce_variation

The variation of Bounce applied to the range of particles.

<UDynaFlect>.chaos Float default: 0.0 -- animatable

Applies a random variation to the bounce angle.

<UDynaFlect>.Friction Float default: 0.0 -- animatable

When set to 0.0 (the default) the surface of the deflector is treated as frictionless, and there's no change in particle behavior. As Friction increases, particles begin to rebound at incorrect angles and with greater speed.

<UDynaFlect>.inheritVelocity Float default: 1.0 -- animatable; alias: velocity_inheritance

Determines how much of a moving UDynaFlect's speed is applied to reflected or refracted particles.

<UDynaFlect>.mass Float default: 1.0 -- animatable; alias: particle_mass

The mass value of the particle.

<UDynaFlect>.'mass units' Integer default: 0 -- animatable; alias: particle_mass_units

Sets the unit of mass to use:

0- Gram

1- Kilogram

2- Pound

<UDynaFlect>.number Integer default: 20 -- animatable

Number of particles.

<UDynaFlect>.radius Float default: 0.0 -- animatable; alias: icon_size

The size of the UDynaFlect icon.

Associated Methods

bindSpaceWarp <node> <UDynaFlect_node>

Associated Binding Modifier

UDynaFlectMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Spacewarp - Particles Only

Note: Spacewarp objects are not available in 3D Studio VIZ.

The following list shows the Particles Only space warp objects:

Deflector

Path_Follow

POmniFlect

SDeflector

SOmniFlect

UDeflector

UOmniFlect


Deflector : SpacewarpObject

Constructor

deflector ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Deflector>.bounce Float default: 1.0 -- animatable

Controls the speed at which particles bounce off the deflector. At a setting of 1.0, particles bounce off the deflector at the same speed they struck it. At 0.0, particles do not bounce at all. At values between 0.0 and 1.0, particles bounce off the deflector at a speed reduced from their initial speed. At values greater than 1.0, particles bounce off the deflector at a speed greater than their initial speed.

<Deflector>.width Float default: 10.0 -- animatable

The deflector's width.

<Deflector>.length Float default: 10.0 -- animatable

The deflector's length.

<Deflector>.variation Float default: 0.0 -- animatable

The bounce variation.

<Deflector>.chaos Float default: 0.0 -- animatable

Angle variation after bounce.

<Deflector>.friction Float default: 0.0 -- animatable

Amount of friction applied to particle.

<Deflector>.inheritVelocity Float default: 0.0 -- animatable

Percentage of deflector's motion inherited by the particle.

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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.

0- Off

1- 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.

<Path_Follow>.Spline_Follow_Type Integer default: 1

Set the follow type:

0- 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.)

1- 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:

0- Off

1- 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:

0- 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.

1- Diverge (Provides the opposite effect of Converge. The particles diverge from the path over time.)

2- 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:

0- Clockwise

1- Counterclockwise

2- 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.

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

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


POmniFlect : SpacewarpObject

Constructor

POmniFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties

<POmniFlect>.deceleration Float default: 1.0 -- animatable

Sets the deceleration of particles.

<POmniFlect>.'decel var' Float default: 0.0 -- animatable; percentage

Affects the variation in deceleration of particles.

<POmniFlect>.friction Float default: 0.0 -- animatable; percentage

When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and there's no change in the particle behavior. As the friction value increases, particles begin to rebound at incorrect angles and with greater speed.

<POmniFlect>.'time on' Integer default: 0 -- animatable; alias: time_on

The frame at which the deflection begins.

<POmniFlect>.'time off' Integer default: 16000 -- animatable; alias: time_off

The frame at which the deflection ends.

<POmniFlect>.affects Float default: 10000.0 -- animatable; alias: reflects

The percentage of particles to be reflected by the POmniFlect.

Controller Scaling: (1 : 100.0)

<POmniFlect>.bounce Float default: 1.0 -- animatable

This multiplier specifies how much of the initial speed of the particle is maintained after collision with the POmniFlect.

<POmniFlect>.bouncevar Float default: 0.0 -- animatable; alias: bounce_variation

The variation of Bounce applied to the range of particles.

Controller Scaling: (1 : 100.0)

<POmniFlect>.chaos Float default: 0.0 -- animatable

Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles bounce off the POmniFlect surface perfectly (like banking pool balls). A non-zero setting causes the deflected particles to scatter.

<POmniFlect>.Refracts Float default: 100.0 -- animatable

The percentage of particles not already reflected that will be refracted by the POmniFlect.

<POmniFlect>.'pass velocity' Float default: 1.0 -- animatable; alias: pass_velocity

Sets how much of a particle's initial speed is maintained after passing through the POmniFlect. The default setting of 1 retains the initial speed is retained, so there's no change. A setting of 0.5 reduces the speed by half.

<POmniFlect>.'passvel var' Float default: 0.0 -- animatable; percentage; alias: Pass_Velocity_Variation

Variation of Pass Velocity applied to the range of particles.

<POmniFlect>.refraction Float default: 50.0 -- animatable; percentage; alias: distortion

Controls the angle of refraction. A value of 0 means there's no refraction. A value of 100% sets the angle of the particles to be parallel with the POmniFlect surface. A value of –100% sets the angle perpendicular to the surface. The Distortion effect is reversed when particles strike the POmniFlect from the back side.

<POmniFlect>.'refraction var' Float default: 0.0 -- animatable; percentage; alias: distortion_variation

Range of variation of the Distortion effect.

<POmniFlect>.Diffusion Float default: 0.0 -- animatable, percentage

Applies a diffusion effect to the refraction by randomly modifying each particle's Distortion angle by the Diffusion angle. This effectively scatters the particles into a hollow cone.

<POmniFlect>.'diffusion var' Float default: 0.0 -- animatable; percentage; alias: diffusion_variation

Range of variation of the Diffusion value.

<POmniFlect>.inheritVelocity Float default: 1.0 -- animatable; alias: velocity_inheritance

Determines how much of a moving POmniFlect's speed is applied to reflected or refracted particles.

<POmniFlect>.spawn Float default: 100.0 -- animatable; percentage; alias: spawn_percentage

The percentage of particles that can use spawn effects.

<POmniFlect>.Pass_Velocity Float default: 1.0 -- animatable

How much of the particle's initial speed is maintained after passing through the POmniFlect.

<POmniFlect>.Pass_Velocity_Variation Float default: 0.0 -- animatable, percentage

The variation of the Pass Velocity setting applied to the range of particles.

<POmniFlect>.width Float default: 0.0 -- animatable

The width of the POmniFlect icon. This is for display purposes only and does not influence the deflector effect.

<POmniFlect>.height Float default: 0.0 -- animatable

The height of the POmniFlect icon. This is for display purposes only and does not influence the deflector effect.

Notes

getPropnames() and showProperties() show two sets of parameters called Pass_Velocity and Pass_Velocity_Variation. The first set is for Refraction, the second for Spawn Effects Only groups. Due to this sharing of property names, you cannot access the Spawn Effects Only Pass_Velocity and Pass_Velocity_Variation using their property names. You can access the value assigned to these parameters, and their controller if assigned, as subAnims 17 and 18 of the base object.

Associated Methods

bindSpaceWarp <particlesys_node> <POmniFlect_node>

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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>.bounce Float default: 1.0 -- animatable

Determines the speed with which particles bounce off the deflector. At 1.0, the particles bounce at the same speed as they approach. At 0, they don't deflect at all.

<SDeflector>.bouncevar Float default: 0.0 -- animatable

The amount by which each particle can vary from the Bounce setting.

<SDeflector>.chaos Float default: 0.0 -- animatable

The amount of variation from the perfect angle of reflection (found when Chaos is set to 0.0). 100% induces a variation in reflection angle of up to 90 degrees

<SDeflector>.inheritVelocity Float default: 1.0 -- animatable; alias: velocity_inheritance

When the value is greater than 0, the motion of the deflector affects particles as well as the other settings. For example, to animate the SDeflector passing through a passive array of particles, turn up this value to affect the particles.

<SDeflector>.radius Float default: 0.0 -- animatable

The diameter of the SDeflector icon. This setting also alters the effect of the deflection, because particles bounce off the perimeter of the icon.

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SOmniFlect : SpacewarpObject

Constructor

SOmniFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties

<SOmniFlect>.'time on' Integer default: 0 -- animatable; alias: time_on

Time at which the deflection starts.

<SOmniFlect>.'time off' Integer default: 16000 -- animatable; alias: time_off

Time at which the deflection ends.

<SOmniFlect>.affects Float default: 100.0 -- animatable, percentage; alias: reflects

The percentage of particles to be reflected by the SOmniFlect.

<SOmniFlect>.bounce Float default: 1.0 -- animatable

This is a multiplier that specifies how much of the initial speed of the particle is maintained after collision with the SOmniFlect. Using the default setting of 1.0 causes the particle to rebound with the same speed as it collides. A real-world effect would usually be less than 1.0. For a "flubber" effect, set greater than 1.0.

<SOmniFlect>.bouncevar Float default: 0.0 -- animatable, percentage; alias: bounce_variation

The variation of Bounce applied to the range of particles.

<SOmniFlect>.chaos Float default: 0.0 -- animatable

Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles bounce off the SOmniFlect surface perfectly (like banking pool balls). A non-zero setting causes the deflected particles to scatter.

<SOmniFlect>.Refracts Float default: 100.0 -- animatable, percentage

The percentage of particles not already reflected that will be refracted by the SOmniFlect.

<SOmniFlect>.'pass velocity' Float default: 1.0 -- animatable; alias: pass_velocity

Defines how much of a particle's initial speed is maintained after passing through the SOmniFlect. The default setting of 1 retains the initial speed is retained, so there's no change. A setting of 0.5 reduces the speed by half.

<SOmniFlect>.'passvel var' Float default: 0.0 -- animatable; percentage; alias: pass_velocity_variation

Variation of the Pass Velocity setting applied to the range of particles.

<SOmniFlect>.refraction Float default: 50.0 -- animatable; percentage; alias: distortion

Controls the angle of refraction. A value of 0 means there's no refraction. A value of 100% sets the angle of the particles to be parallel with the SOmniFlect surface. A value of –100% sets the angle perpendicular to the surface. The Distortion effect is reversed when particles strike the SOmniFlect from the back side.

<SOmniFlect>.'refraction var' Float default: 0.0 -- animatable; percentage; alias: distortion_variation

Range of variation of the Distortion effect.

<SOmniFlect>.Diffusion Float default: 0.0 -- animatable, percentage

Applies a diffusion effect to the refraction by randomly modifying each particle's Distortion angle by the Diffusion angle. This effectively scatters the particles into a hollow cone.

<SOmniFlect>.'diffusion var' Float default: 0.0 -- animatable; percentage; alias: diffusion_variation

Range of variation of the Diffusion value.

<SOmniFlect>.inheritVelocity Float default: 1.0 -- animatable; alias: velocity_inheritance

Determines how much of a moving SOmniFlect's speed is applied to reflected or refracted particles.

<SOmniFlect>.deceleration Float default: 1.0 -- animatable

Sets the deceleration of particles.

<SOmniFlect>.'decel var' Float default: 0.0 -- animatable; percentage

Sets the variation in deceleration of particles.

<SOmniFlect>.spawn Float default: 100.0 -- animatable; percentage; alias: spawn_percentage

The percentage of particles that can use spawn effects.

<SOmniFlect>.friction Float default: 0.0 -- animatable; percentage

When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and there's no change in the particle behavior. As the friction value increases, particles begin to rebound at incorrect angles and with greater speed.

<SOmniFlect>.radius Float default: 0.0 -- animatable

The radius of the SomniFlect icon.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


UDeflector : SpacewarpObject

Constructor

uDeflector ...

Note: This class is not available in 3D Studio VIZ.

Properties

<UDeflector>.bounce Float default: 1.0 -- animatable

The speed with which particles bounce off the deflector. At 1.0, the particles bounce at the same speed as they approach. At 0, they don't deflect at all.

<UDeflector>.bouncevar Float default: 0.0 -- animatable

The amount by which each particle can vary from the Bounce setting.

<UDeflector>.chaos Float default: 0.0 -- animatable

The amount of variation from the perfect angle of reflection (found when Chaos is set to 0.0). 100% induces a variation in reflection angle of up to 90 degrees.

<UDeflector>.Friction Float default: 0.0 -- animatable, percentage

Determines the amount of tangential "stick" at the surface as particles bounce off the deflector.

<UDeflector>.inheritVelocity Float default: 1.0 -- animatable; alias: velocity_inheritance

When greater than 0, the motion of the deflector affects particles as well as the other settings. For example, to animate the SDeflector passing through a passive array of particles, increase this value to affect the particles.

<UDeflector>.radius Float default: 0.0 -- animatable; alias: icon_size

The size of the Udeflector icon.

Notes

There is no way to set the Deflector object using MAXScript in 3ds max 4.

Associated Methods

bindSpaceWarp <particlesys_node> <uDeflector_node>

Associated Binding Modifier

UDeflectorMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


UOmniFlect : SpacewarpObject

Constructor

UOmniFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties

<UOmniFlect>.'time on' Integer default: 0 -- animatable; alias: time_on

Time at which deflection starts.

<UOmniFlect>.'time off' Integer default: 16000 -- animatable; alias: time_off

Time at which deflection ends.

<UOmniFlect>.affects Float default: 10000.0 -- animatable; percentage; alias: reflects

Percentage of particles to be reflected by the UOmniFlect.

<UOmniFlect>.bounce Float default: 1.0 -- animatable

This multiplier specifies how much of the initial speed of the particle is maintained after collision with the UOmniFlect.

<UOmniFlect>.bouncevar Float default: 0.0 -- animatable; percentage; alias: bounce_variation

Specifies the variation of Bounce applied to the range of particles.

<UOmniFlect>.chaos Float default: 0.0 -- animatable

Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles bounce off the UOmniFlect surface perfectly (like banking pool balls). A non-zero setting causes the deflected particles to scatter.

<UOmniFlect>.Refracts Float default: 100.0 -- animatable, percentage

Specifies the percentage of particles not already reflected that will be refracted by the UOmniFlect.

<UOmniFlect>.'pass velocity' Float default: 1.0 -- animatable; alias: pass_velocity

Specifies how much of a particle's initial speed is maintained after passing through the UOmniFlect.

<UOmniFlect>.'passvel var' Float default: 0.0 -- animatable; percentage; alias: pass_velocity_variation

Specifies the variation of Pass Velocity applied to the range of particles.

<UOmniFlect>.refraction Float default: 50.0 -- animatable; percentage; alias: distortion

Controls the angle of refraction. A value of 0 means there's no refraction. A value of 100% sets the angle of the particles to be parallel with the UOmniFlect surface. A value of –100% sets the angle perpendicular to the surface. The Distortion effect is reversed when particles strike the UOmniFlect from the back side.

<UOmniFlect>.'refraction var' Float default: 0.0 -- animatable; percentage; alias: distortion_variation

Specifies a range of variation of the Distortion effect.

<UOmniFlect>.Diffusion Float default: 0.0 -- animatable, percentage

Applies a diffusion effect to the refraction by randomly modifying each particle's Distortion angle by the Diffusion angle. This effectively scatters the particles into a hollow cone.

<UOmniFlect>.'diffusion var' Float default: 0.0 -- animatable; percentage; alias: diffusion_variation

Specifies a range of variation of the Diffusion value.

<UOmniFlect>.Friction Float default: 0.0 -- animatable

When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and there's no change in the particle behavior. As the Friction value increases, particles begin to rebound at incorrect angles and with greater speed.

<UOmniFlect>.inheritVelocity Float default: 1.0 -- animatable; alias: velocity_inheritance

Determines how much of a moving UOmniFlect's speed is applied to reflected or refracted particles.

<UOmniFlect>.deceleration Float default: 1.0 -- animatable

The deceleration value for the particles.

<UOmniFlect>.'decel var' Float default: 0.0 -- animatable; percentage

The range of variation in decelerations values.

<UOmniFlect>.spawn Float default: 100.0 -- animatable; percentage; alias: spawn_percentage

Specifies the percentage of particles that can use spawn effects

<UOmniFlect>.Pass_Velocity Float default: 1.0 -- animatable

Specifies how much of the particle's initial speed is maintained after passing through the UOmniFlect.

<UOmniFlect>.Pass_Velocity_Variation Float default: 0.0 -- animatable, percentage

Specifies the variation of the Pass Velocity setting applied to the range of particles.

<UOmniFlect>.radius Float default: 0.0 -- animatable; alias: icon_size

The size of the UOmniFlect icon.

Notes

getPropnames() and showProperties() show two sets of parameters called Pass_Velocity and Pass_Velocity_Variation. The first set is for Refraction, the second for Spawn Effects Only groups. Due to this sharing of property names, you cannot access the Spawn Effects Only Pass_Velocity and Pass_Velocity_Variation using their property names. You can access the value assigned to these parameters, and their controller if assigned, as subAnims 17 and 18 of the base object.

Associated Methods

bindSpaceWarp <particlesys_node> <UOmniFlect_node>

Associated Binding Modifier

UOmniFlectMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


XRefObject : Node

A XRefObject value represents an XRef object in 3ds max. A XRefObject value is returned when the xrefs.addNewXRefObject() function is called. There are two objects associated with an XRef object in 3ds max – the non-proxy object and the proxy object. The proxy object is typically a lower resolution object that is used as a standin for the non-proxy object in the viewports.

Constructor

xrefs.addNewXRefObject <filename_string> <objectname_string> [#proxy]

Loads the specified node object from the specified scene file as an XRef object. The case of objectname_string must match the object's name in the scene file. If #proxy is specified, the node object is loaded as the proxy object, otherwise it is loaded as the non-proxy object.

The XRefObject is always loaded at world center.

Properties

<XRefObject>.proxyFileName String default: varies

The file name of the proxy object.

<XRefObject>.fileName String default: varies

The file name of the non-proxy object.

<XRefObject>.currentFileName String default: varies

The file name of the non-proxy object if the useProxy property is false, the file name of the proxy object if the useProxy property is true.

<XRefObject>.objectName String default: varies

The name of the proxy object.

<XRefObject>.proxyObjectName String default: varies

The name of the non-proxy object.

<XRefObject>.currentObjectName String default: varies

The name of the non-proxy object if the useProxy property is false, the name of the proxy object if the useProxy property is true.

<XRefObject>.useProxy Boolean default: varies

If true, the proxy object will be displayed in the viewports, otherwise the non-proxy object will be displayed. If the XRef object is added to the scene using the xrefs.addNewXRefObject() method, this parameters default value will be true if #proxy is specified, false otherwise.

<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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

Note:

Scenes with a script controller whose script has explicit references ($sphere01, etc.) to objects in an incoming xref scene have a problem where the objects in the xref scene are invisible to MAXScript, and so the script will fail. This is actually a general problem with xrefs, you cannot have scripts of any kind in the xref scene (scripts controllers, param wires, callback scripts, etc.) that depend on explicit scene object references.

However, 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 to address the problem stated above, 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 and 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. So the all the scripts should use persistent globals and not have explicit node name references.

Constructor

xrefs.addNewXRefFile <filename_string> [ #noLoad ] [root:<XRefScene>]

Adds a new XRef Scene object and returns a XRefScene value. If #noLoad is not specified, the XRef Scene file is loaded immediately and the scene updated. If #noLoad is specified, the scene is not updated until the user requests it. Use the updateXRef() method to load the XRef Scene object.

If root:<XRefScene> is specified, the XRef Scene object is treated in the current file during the current session as if it was an XRef Scene object in the file corresponding to the XRefScene value specified. If the specified root XRef Scene object is reloaded, either because the current scene was saved and then reloaded, or because updateXRef() was executed on the root XRef Scene object, the XRef Scene object is deleted from the scene.

xrefs.getXRefFile <index> [root:<XRefScene>]

If root is not specified, returns the XRefScene value corresponding to the indexed XRef Scene object in the XRef Scenes dialog. If the root:<XRefScene> is specified, the XRefScene value corresponding to a nested XRef Scene object within the XRefScene's XRef Scene object is returned. The index is 1-based, and corresponds to the order of the XRef Scene objects listed in the XRef Scenes dialog. You can use the xrefs.getXRefFileCount() method to determine the number of XRef Scene objects in the scene.

Properties

<XRefScene>.filename String default: varies

The file name of the XRef Scene object. If you change this property to a new scene file name, the objects in the specified file are displayed, replacing the objects from the initial scene file.

<XRefScene>.tree Node

The root node of the XRef Scene object. This is a read-only property. You can access the children objects in an XRef Scene object using this property. For example:

aXref=xrefs.getXRefFile 1 -- returns first XRef Scene object

aXref.tree.children -- objects in the XRef Scene object,

-- for example, may return:

-- #children($Box01, $Box02)

aXref.tree.children[1].width—returns width value of $Box01

<XRefScene>.parent Node default: undefined

The parent of the XRef Scene object. By default this is undefined but can be set to any node in the scene.

<XRefScene>.autoUpdate Boolean default: false

If true, automatic XRef file updating is on.

<XRefScene>.boxDisp Boolean default: false

If true, all nodes the in the XRef Scene object are displayed in Box display mode.

<XRefScene>.hidden Boolean default: false

If true, the XRef Scene object is hidden.

<XRefScene>.disabled Boolean default: false

If true, the XRef Scene object is disabled.

<XRefScene>.ignoreLights Boolean default: false

If true, the lights in the XRef Scene object will not be displayed.

<XRefScene>.ignoreCameras Boolean default: false

If true, the cameras in the XRef Scene object will not be displayed.

<XRefScene>.ignoreShapes Boolean default: false

If true, the shapes in the XRef Scene object will not be displayed.

<XRefScene>.ignoreHelpers Boolean default: false

If true, the helpers in the XRef Scene object will not be displayed.

<XRefScene>.ignoreAnimation Boolean default: false

If true, any animation in the XRef Scene object will be ignored.

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

SplineShape

Patch


Editable_Mesh : GeometryClass and TriMesh : Value

Editable_Mesh is the class of node objects that are the result of collapsing a modifier stack to an editable mesh object. Many of the mesh operations in MAXScript that modify meshes will only work on Editable_Mesh scene nodes.

The TriMesh class is a MAXScript value wrapper for the low-level 3ds max SDK Mesh class used extensively in mesh-based objects and modifiers in 3ds max. Meshes hold the actual vertex and face arrays, and so on, in a triangular mesh. For example, an Editable_Mesh object contains an instance of a Mesh. The prime purpose of the TriMesh class is to allow scripted primitive object plug-ins to access and build the Mesh object inside geometry objects. This class has a large range of mesh manipulation and construction functions, corresponding to the low-level mesh operations on Editable Mesh scene nodes.

The properties and methods described in this topic are applicable to both Editable_Mesh objects and TriMesh values are signified by a value type of <mesh>. The properties and methods applicable to just TriMesh values are signified by a value type of <trimesh>.

Warning: Meshes created by MAXScript are triMesh values.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Class and Object Inspector Functions

Scripting Vertex and Control Point Animation

Notes

  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.

  3. If the update() function is called on an object that is selected and currently open in the Modify panel, it will drop the current selection in order to avoid a potential crash in 3ds max, which at the moment, does not support scripted changes to an object open in the Modify panel.

  4. If you are creating or modifying a mesh, and have not yet run update() on the mesh, 3ds max will crash if you minimize and then maximize the 3ds max window. This is because an only partially created mesh is created, and the internal 3ds max mesh structure is left in an unstable state.

Constructors (Editable_Mesh)

mesh [ length:<integer> ] [ width:<integer> ] \

[ lengthsegs:<integer> ] [ widthsegs:<integer> ]

Creates a flat rectangular mesh with the given size and number of segments. The default length and width are 50, the default number of segments is 5.

mesh [ numverts:<number> ] [ numfaces:<number> ]

Creates a mesh of the given geometry but with no topology (i.e., no faces or edges). You have to individually place the vertices and create the faces from the vertices. The default number of vertices and faces are 36 and 50, respectively.

mesh vertices:<array_of_point3s> \

faces:<array_of_point3s> \

[ materialIDs:<array_of_integers> ] \

[ tverts:<array_of_point3s> ]

Creates a mesh from an array of vertices and faces. Each Point3 value in the vertices array specifies the position of the vertex in the current coordinate system. Each Point3 value in the faces array specifies the 3 vertex indices that form the face. The materialIDs array specifies the material ID to be assigned to each face. Each Point3 value in the tverts array specifies the UVW coordinates of the texture vertices. See Texture Mapping in the methods section for more information on texture vertices.

An example of construction a mesh using this form of the constructor is:

mesh vertices:#([0,0,0],[10,0,0],[0,10,0],[10,10,0]) \

faces:#([1,2,3],[2,4,3]) materialIDS:#(1,2)

collapseStack <node> -- mapped

Collapses the object space modifiers out of a stack, leaving a resultant Editable Mesh as the base object of the node. If there are no object space modifiers in the stack when this is called, no action is taken. So, if you want to force an object to be an editable mesh (for example, for the mesh operation listed below), you can apply a null modifier and then collapse the stack:

addModifier $foo (normalModifier())

collapseStack $foo

collapseStack() does not collapse the effect of any world space modifiers (including bindings to space warps). The world space modifiers remain on the object's stack. To collapse an object to a mesh use the snapshot() method.

snapshot <node> -- mapped

This function provides functionality similar to the SnapShot tool in 3ds max. It generates a new node that contains a copy of the world-state mesh of the source <node> at the time that the snapshot is made. Any existing modifiers are collapsed out of the new node and the mesh snapshot accounts for any space warps currently applied.

convertToMesh <node> -- mapped

Converts appropriate scene object types into Editable Meshes. It is similar to collapseStack() in that it will remove all object space modifiers present, but unlike collapseStack() it will always replace the base object with an editable mesh version, even if there are no modifiers present.

It can be applied to any object that an Edit Mesh modifier can work on, such as geometry and shapes, but not helpers, space warps, lights, etc.

convertTo <node> [ TriMeshGeometry | Mesh ] -- mapped

Converts appropriate scene object types into Editable Meshes. Operates in an identical manner to convertToMesh().

Constructors (TriMesh)

TriMesh()

Creates an empty TriMesh. Use the methods listed below to build the mesh.

<node>.mesh

Extracts a copy of a node's world state if it is convertible to a mesh.

<editable_mesh_baseobject>.mesh

Extracts a copy of base object's mesh.

<trimesh>.mesh

Extracts a copy of another TriMesh's mesh.

Notes

GeometryClass boolean operations also create editable_mesh objects.

Operators

The following operators perform boolean operations on meshes. These operations destructively modify the first operand mesh to contain the boolean result, as do the same boolean <node> operations.

<mesh> + <mesh> -- union

<mesh> - <mesh> -- difference

<mesh> * <mesh> -- intersection

Properties

<mesh>.numverts Integer

Get or set the number of vertices

<mesh>.numfaces Integer

Get or set the number of faces

<mesh>.numtverts Integer

Get or set the number of texture vertices

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

<mesh>.verts VertexArray

Get all of the vertices of the Editable_Mesh object. See VertexSelection Values.

<mesh>.selectedFaces FaceArray

Get the currently selected faces of the Editable_Mesh object. See FaceSelection Values.

<mesh>.Faces FaceArray

Get all of the faces of the Editable_Mesh object. See FaceSelection Values.

<mesh>.selectedEdges EdgeArray

Get the currently selected edges of the Editable_Mesh object. See EdgeSelection Values.

<mesh>.Edges EdgeArray

Get all of the edges of the Editable_Mesh object. See EdgeSelection Values.

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

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 Scripting Vertex and Control Point Animation. For example, if a sphere object is collapsed to an Editable_Mesh, and some of its vertices are animated, the properties for the vertices would be similar to:

$Sphere01.vertex_209 Point3 value: [7.9,-40.0,0.0] -- animatable

$Sphere01.vertex_210 Point3 value: [-7.8,-39.3,-7.9] -- animatable

$Sphere01.vertex_211 Point3 value: [0.0,-40.0,-7.9] -- animatable

Methods

The following methods operate on the base object in a node if no object space modifiers are present. If object space modifiers are present, the mesh get operations access the world-state mesh, after the object space modifiers have been applied. The mesh set operations only work on base object Editable Meshes and signal an error if there are object space modifiers present, informing you that the mesh is not changeable when modifiers are present. You can convert objects to Editable Meshes with the collapseStack(), snapshot(), and convertToMesh() methods. If there are no object space modifiers present, both get and set operations work on the base editable mesh object.

Because the mesh get operations require a mesh, the combination of base object and modifiers must yield a mesh at the top of the modifier stack. This excludes combinations such as Patch base-objects and deformer modifiers such as bend and twist, because they pass a patch object, not a mesh up the stack. Applying an Edit Mesh modifier always forces the world-state object to be a mesh.

If world space modifiers are present, the mesh get operations access the world-state mesh, after any object space modifiers have been applied, but before the world space modifiers have been applied. Currently you can not access the position of vertices as affected by world space modifiers. The mesh set operations will work if only world space modifiers are applied to the object. Setting a vertices position in such a case will set it's position before the world space modifiers have been applied. You can create a new mesh object using the snapshot() method which accounts for the effects of world space modifiers.

The update() method makes any scripted changes to a base object mesh visible to 3ds max and you must call this function at some point after modifying a mesh so that 3ds max sees a valid mesh. Because this update can be a compute-intensive operation, it is made available as a separate function so you perform many changes on a mesh and then invoke the update just once to signal all the changes to 3ds max.

All vertex and face indexes start at 1, following the other indexing conventions in MAXScript. All coordinates used are relative to the current working coordinate system.

General Methods

update <mesh> [ geometry:<boolean> ] [ topology:<boolean> ] \

[ normals:<boolean> ] -- mapped

The three optional keyword arguments provide control over the kind of updating done to the mesh. If the geometry: argument is true, the geometry cache is rebuilt (normals and edge list) and the mesh's bounding box is invalidated. If the topology: argument is true, the edge and strip databases will be rebuilt. If normals: is true, the face normals are computed. All flags default to true, so that a simple call to update() causes a complete reconstruction of all the caches.

attach <mesh> <node>

Corresponds to the mesh attach function in the Editable Mesh Modify panel allowing you to construct a mesh by adding complete objects to it. Extracts the mesh from <node> (first converting to a mesh if need), adds it to <mesh> which must be an Editable Mesh object and then deletes <node>. The materials and material IDs in <node> are merged into <node> using the default settings for the attach operation in the Editable Mesh Modify panel. This method is not applicable to TriMeshes.

meshop.attach {<target_editable_mesh_node> | <target_mesh>}

{<source_node> | <source_mesh>} \ targetNode:<node=unsupplied>

sourceNode:<node=unsupplied> \ attachMat:<{#neither | #MatToID |

#IDToMat}=#neither> condenseMat:<boolean=true> \ deleteSourceNode:<boolean=true>

Attaches the source mesh to the target mesh. If the target or source is specified as a mesh rather than a node, the mesh is attached using the local coordinate system of the mesh, and no material correction is performed. To get around this, if the target or source is a mesh, the corresponding targetNode or sourceNode named parameter is checked to see if a node is specified and, if it is, the transform and material for that node is used. If the source or target is specified as a node, the corresponding targetNode or sourceNode named parameter is not checked. The attachMat and condenseMat options correspond to the attach options in editable mesh.

condenseMat is applicable only if attachMat:#IDToMat is specified. If deleteSourceNode:false is not specified, and the source was specified as a node, or as a mesh and a sourceNode was specified, the source node is deleted after the attach.

Examples:

meshop.attach $.baseobject $sphere02 targetNode:$

meshop.attach $box01 $box02 attachMat:#IDToMat

condenseMat:true deleteSourceNode:false

meshop.getUIParam <mesh> <param_name>

meshop.getUIParam <node> [ <modifier_or_index> ] <param_name>

meshop.setUIParam <mesh> <param_name> { <float> | <boolean> }

meshop.setUIParam <node> [ <modifier_or_index> ] <param_name> { <number> | <boolean> }

Get/set a user-interface value. The optional <modifier_or_index> identifies the Edit Mesh modifier on the given scene object to set the parameter value for. These methods are UI-dependent, and require that the specified editable mesh or Edit Mesh modifier be currently displayed in the Modify panel. The valid param_name values, their meaning, and parameter value type are:

#SelByVert Selection - By Vertex (boolean)

#IgBack Selection - Ignore Backfacing (boolean)

#IgnoreVis Selection - Ignore Visibile Edges (boolean)

#PolyThresh Selection - Planar Threshold (number)

#SoftSel Soft Selection - Use Soft Selection (boolean)

#SSUseEDist Soft Selection - Edge Distance (boolean)

#SSEDist Soft Selection - Edge Distance (number) [note: if value hasn't been changed, returns a value of 0]

#SSBack Soft Selection - Ignore Backfacing (boolean) [note: this is the inverse of the UI element]

#Falloff Soft Selection - Falloff (number)

#Pinch Soft Selection - Pinch (number)

#Bubble Soft Selection - Bubble (number)

#WeldDist Weld - Distance (number)

#WeldBoxSize Weld - Box Size in Pixels (number)

#ExtrudeType Extrude/Chamfer (boolean) [note: true - Group; false - Local]

#ShowVNormals Show Vertex Normals (boolean)

#ShowFNormals Show Face Normals (boolean)

#NormalSize Normal Scale (number)

Vertex methods

meshop.breakVerts <Mesh mesh> <vertlist>

For each vertex in <vertlist>, N-1 new vertices are created at the same location, where N is the number of faces using that vertex. Each of these faces will use one of these vertices.

meshop.chamferVerts <Mesh mesh> <vertlist> <float amount>

Chamfers the specified vertices by the specified amount.

meshop.cloneVerts <Mesh mesh> <vertlist>

Clones the specified vertices.

meshop.cutVert <Mesh mesh> <int start_vert> <point3 destination> <point3 projdir> node:<node=unsupplied>

If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, destination and projdir are in the current coordinate system context. If <mesh> is an Editable Mesh and <node> is not specified, destination and projdir are in the mesh's local coordinate system.

Returns the index of the new vertex if created, or undefined if no vertex was created.

meshop.deleteIsoVerts <Mesh mesh>

Deletes all vertices not used by a face.

meshop.deleteVerts <Mesh mesh> <vertlist>

Deletes the specified vertices.

meshop.detachVerts <Mesh mesh> <vertlist> delete:<boolean=true> asMesh:<boolean=false>

Detaches the faces used by the specified vertices. If <delete> is true, the faces are deleted after being detached. If <delete> is false, the faces are not deleted. If <asMesh> is true, the faces are detached and returned as a Mesh value. If <asMesh> is false, the faces are detached as an element in the mesh and a value of OK is returned.

meshop.getHiddenVerts <Mesh mesh>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are hidden.

meshop.getIsoVerts <Mesh mesh>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are not used by a face.

meshop.getNumVerts <Mesh mesh>

Returns the number of vertices in the mesh.

meshop.getVert <Mesh mesh> <int vertIndex> node:<node=unsupplied>

Returns the position of the specified vertex. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position returned is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the return value is in the mesh's local coordinate system.

meshop.getVertexAngles <Mesh mesh> <vertlist>

This method calculates, for each vertex, the sum of the angles of this vertex's corner in each face it's on. So for instance, a point lying in the middle of a grid would always have vertex angle 2*PI, whereas a corner of a box would only have 270. Returns an array of size=(#vertices in mesh). The array element for any vertices not specified in <vertlist> will contain the value 0.

meshop.getVertsByColor <Mesh mesh> <color color> <float red_thresh> <float green_thresh> <float blue_thresh> channel:<int=0>

Returns the vertices whose vertex color is within the color range as a <bitarray>. The range values should be in the range of 0 to 255.

meshop.getVertsByColor <Mesh mesh> <point3 uvw> <Float u_thresh> <Float v_thresh> <Float w_thresh> channel:<int=0>

Returns the vertices whose vertex UVW is within the UVW range as a <bitarray>. The range values should be in the range of 0 to 1.

meshop.makeVertsPlanar <Mesh mesh> <vertlist>

Moves the specified vertices so that they are planar.

meshop.minVertexDistanceFrom <Mesh mesh> <int vertIndex> <vertlist>

Returns the minimal distance from <vertIndex> to the vertices specified in <vertlist>.

meshop.minVertexDistancesFrom <Mesh mesh> <vertlist> <int iterations>

This function computes distances from selected vertices (as indicated by <vertlist>) to non-selected ones along edge paths. Returns an array of size=(#vertices in mesh). Each element in this array is set to -1 if there is no selection. Otherwise, selected vertices have an array element value of 0; non-selected vertices that are <iterations> or fewer edges away from a selected vertex are assigned the shortest edge-path distance to a selected vertex; and non-selected vertices that are more than <iterations> edges away are set to -1. If <iterations> is 0, the distances are computed from each vertex to the nearest selected vertex, regardless of topology. This is a VERY EXPENSIVE ALGORITHM, which takes almost 4 times as long for twice as many vertices. If <iterations> is non-zero, it represents the number of edges one should "travel" in trying to find the nearest selected vertex—this means that it only takes twice as long for twice as many verts. (This is like the Edge Distance parameter in EMesh's Soft Selection dialog.)

meshop.moveVert <Mesh mesh> <vertlist> <point3 offset> node:<node=unsupplied>

Moves the specified vertices by <offset>. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the offset is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the offset is in the mesh's local coordinate system.

meshop.moveVertsToPlane <Mesh mesh> <vertlist> <point3 normal> <float offset> node:<node=unsupplied>

Moves the specified vertices into the specified plane. The target plane is defined as all points which, when DotProd'd with N, return offset. All vertices are moved along the normal vector N. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the normal is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the normal is in the mesh's local coordinate system.

meshop.setHiddenVerts <Mesh mesh> <vertlist>

Sets the specified vertices as hidden, and non-specified vertices as visible.

meshop.setNumVerts <Mesh mesh> <int>

Sets the number of vertices in the mesh. Any new vertices are created at [0,0,0] in the mesh's local coordinate system.

meshop.setVert <Mesh mesh> <vertlist> <point3 pos> node:<node=unsupplied>

Moves the specified vertices to the specified position. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the mesh's local coordinate system.

meshop.setVertColor <Mesh mesh> <int mapChannel> <vertlist> <Color color>

Sets the vertex color for the specified vertices in the specified <mapChannel>.

meshop.weldVertsByThreshold <Mesh mesh> <vertlist> <float threshold>

Welds the specified vertices that are within the threshold distance.

meshop.weldVerts - renamed to weldVertSet

meshop.weldVertSet <Mesh mesh> <vertlist> weldpoint:<point3=unsupplied> node:<node=unsupplied>

Welds the specified vertices. If <weldpoint> is specified, the resulting vertex is positioned at that point. The result is put at the average location of the selected vertices. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the mesh's local coordinate system. If <weldpoint> is not specified, the resulting vertex is positioned at the average location of the specified vertices.

Vertex data methods

meshop.setNumVDataChannels <Mesh mesh> <Integer count> keep:<boolean=false>]

Sets the number of vertex data channels available. The number of vertex data channels can be set from 0 to 100. The first ten channels are for Discreet's use only. If keep is false or not specified, the old channel data is discarded. If true, the old channel data is retained after the resize. The predefined channels are:

channel 1: Soft Selection

channel 2 Vertex weights (for NURMS MeshSmooth)

channel 3 Vertex Alpha values

channel 4 Cornering values for subdivision use

meshop.getNumVDataChannels <Mesh mesh>

Returns the number of vertex data channels available as an <integer>.

meshop.setVDataChannelSupport <Mesh mesh> <Integer vdChannel> <Boolean support>

Sets whether the specified vertex data channel is supported or not. If support is true, and the channel support state is currently false, a new vertex data array of the same size as the number of vertices in the mesh is allocated. If support is false, and the channel support state is currently true, the existing vertex data channel array is deallocated. If support and the current channel support state are both the same, no action is performed. setNumVDataChannels() is automatically called if the specified vertex data channel is not available. vdChannel index values are 1-based, with channels 1 and 2 being the Vertex Soft Selection and Vertex Weight channels.

meshop.getVDataChannelSupport <Mesh mesh> <Integer vdChannel>

Returns whether the specified vertex data channel is supported.

meshop.getVDataValue <Mesh mesh> <Integer vdChannel> <Integer vert_index>

Returns the floating point data value associated with vertex vert_index in vertex data channel vdChannel as a <float>.

meshop.setVDataValue <Mesh mesh> <Integer vdChannel> <Integer vert_index> <Float value>

Sets the floating point data value associated with vertex vert_index in vertex data channel vdChannel.

meshop.freeVData <Mesh mesh> <Integer vdChannel>

Deallocates the existing vertex data channel array and turns off the vertex data channel support state.

Edge methods

meshop.chamferEdges <Mesh mesh> <edgelist> <float amount>

Chamfers the specified edges by the specified amount.

meshop.cloneEdges <Mesh mesh> <edgelist>

Clones the specified edges.

meshop.collapseEdges <Mesh mesh> <edgelist>

Collapses the specified edges.

meshop.cutEdge <Mesh mesh> <int edge1> <float prop1> <int edge2> <float prop2> <point3 projdir> node:<node=unsupplied>

If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, projdir is in the current coordinate system context. If <mesh> is an Editable Mesh and <node> is not specified, projdir is in the mesh's local coordinate system.

Returns the index of the new vertex if created, or undefined if no vertex was created.

meshop.deleteEdges <Mesh mesh> <edgelist> delIsoVerts:<boolean=true>

Deletes the specified edges. If <delIsoVerts> is true, any isolated vertices are deleted.

meshop.divideEdge <Mesh mesh> <int edgeIndex> <float edgef> visDiag1:<boolean=false> visDiag2:<boolean=false> fixNeighbors:<boolean=true> split:<boolean=false>

Divides the specified edge at a fractional distance of <edgef> along its length. <visDiag1> and <visDiag2> specify whether each of the two new edges will be visible. If <fixNeighbors> is true, the face on the other side of this edge, that is, the "reverse face", should be divided as well to prevent the introduction of a seam. If <split> is true, separate vertices for the two halves of the edge will be created, splitting the mesh open along the diagonal(s).

meshop.divideEdges <Mesh mesh> <edgelist>

Divides all the specified edges in half, creating new points and subdividing faces.

meshop.edgeTessellate <Mesh mesh> <facelist> <float tension>

Tessellates the specified edges. This algorithm is exactly the one used in the Tessellate modifier, when operating on Faces and Edge SO elements.

<tension> specifies the tension for the edge tessellation. This value should be fairly small, between 0 and .5, and corresponds to the value in the Tessellate, Edit Mesh, or Editable Mesh UI's divided by 400.

meshop.extrudeEdges <Mesh mesh> <edgelist> <float height> dir:<{<point3 dir> | #independent | #common}=#independent> node:<node=unsupplied>

Creates new edges corresponding to the specified edges, and then moves the new edges by <height>. The direction the edges are moved is determined by <dir>. If <dir> is a point3 value, the edges will be moved in that direction. (If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the direction is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the direction is in the mesh's local coordinate system.) If dir:#independent is specified, the edges are moved based on the normals of the faces using the edge. If dir:#common is specified, the edges are moved based on the normals of the face clusters using the edge.

meshop.getEdgesUsingVert <Mesh mesh> <vertlist>

Returns a bitarray of size=(#edges in mesh) with bits set for all edges that use the specified vertices.

meshop.getOpenEdges <Mesh mesh>

Returns a bitarray of size=(#edges in mesh) with bits set for all edges that are used by a single face.

meshop.turnEdges - renamed to turnEdge, still showing in index

meshop.turnEdge <Mesh mesh> <int edgeIndex>

Turns the specified edge. Only works on edges that have a face on both sides. These two faces are considered as a quad, where this edge is the diagonal, and remapped so that the diagonal flows the other way, between the vertices that were opposite this edge on each face.

Face methods

meshop.bevelFaces <Mesh mesh> <facelist> <float height> <float outline> dir:<{<point3 dir> | #independent | #common}=#independent> node:<node=unsupplied>

Moves the specified faces by <height> and outlines them by <outline>. The direction the faces are moved is determined by <dir>. If <dir> is a point3 value, the faces will be moved in that direction. (If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the direction is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the direction is in the mesh's local coordinate system.) If dir:#independent is specified, the faces are moved based on the individual face normals. If dir:#common is specified, the faces are moved based on the face cluster normals.

meshop.cloneFaces <Mesh mesh> <facelist>

Clones the specified faces.

meshop.collapseFaces <Mesh mesh> <facelist>

Collapses the specified faces.

meshop.cutFace <Mesh mesh> <int face> <point3 start> <point3 destination> <point3 projdir> node:<node=unsupplied>

If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, start, destination, and projdir are in the current coordinate system context. If <mesh> is an Editable Mesh and <node> is not specified, start, destination, and projdir are in the mesh's local coordinate system.

Returns the index of the new vertex if created, or undefined if no vertex was created.

meshop.deleteFaces <Mesh mesh> <facelist> delIsoVerts:<boolean=true>

Deletes the specified faces. If <delIsoVerts> is true, any isolated vertices are deleted.

meshop.detachFaces <Mesh mesh> <facelist> delete:<boolean=true> asMesh:<boolean=false>

Detaches the specified faces. If <delete> is true, the faces are deleted after being detached. If <delete> is false, the faces are not deleted. If <asMesh> is true, the faces are detached and returned as a Mesh value. If <asMesh> is false, the faces are detached as an element in the mesh and a value of OK is returned.

meshop.divideFace <Mesh mesh> <int faceIndex> baryCoord:<point3=unsupplied>

Divides the specified face. If <baryCoord> is specified, the new vertex will be created at the corresponding position. If <baryCoord> is not specified, the new vertex will be created at the center of the face.

meshop.divideFaceByEdges <Mesh mesh> <int faceIndex> <int edge1Index> <float edge1f> <int edge2Index> <float edge2f> fixNeighbors:<boolean=true> split:<boolean=false>

Divides the specifed face. New vertices are created on the specified edges at the specified fractional distance along their length. If <fixNeighbors> is true, the face on the other side of the edges, that is, the "reverse faces", should be divided as well to prevent the introduction of a seam. If <split> is true, separate vertices for the two halves of the edges will be created, splitting the mesh open along the diagonal(s).

meshop.divideFaces <Mesh mesh> <facelist>

Divides the specified faces, with new vertices created at the center of the faces.

meshop.explodeAllFaces <Mesh mesh> <float threshold>

"Explodes" the mesh into separate elements.

<threshold> specifies the angle between faces that indicates whether they should be in the same or different element.

meshop.explodeFaces <Mesh mesh> <facelist> <float threshold>

"Explodes" the specified faces into separate elements.

<threshold> specifies the angle between faces that indicates whether they should be in the same or different element.

meshop.extrudeFaces <Mesh mesh> <facelist> <float height> <float outline> dir:<{<point3 dir> | #independent | #common}=#independent> node:<node=unsupplied>

Creates new faces corresponding to the specified faces, and then moves the new faces by <height> and outlines them by <outline>. The direction the faces are moved is determined by <dir>. If <dir> is a point3 value, the faces will be moved in that direction. (If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the direction is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the direction is in the mesh's local coordinate system.) If dir:#independent is specified, the faces are moved based on the individual face normals. If dir:#common is specified, the faces are moved based on the face cluster normals.

meshop.getBaryCoords <Mesh mesh> <int faceIndex> <point3 pos> node:<node=unsupplied>

The barycentric coordinates of the specified point in the plane of the specified face, relative to the face. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the mesh's local coordinate system.

meshop.getElementsUsingFace <Mesh mesh> <facelist> fence:<facelist=unsupplied>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces in elements where at least one face in the element is specified in <facelist>. If <fence> is specified, its faces are considered as barriers to the element and are not processed.

meshop.getFaceCenter <Mesh mesh> <int faceIndex> node:<node=unsupplied>

Returns the face center of the specified face. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the mesh's local coordinate system.

meshop.getFaceRNormals <Mesh mesh> <int faceIndex> node:<node=unsupplied>

Returns a three element array of the render normals for the face's three vertices. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the mesh's local coordinate system.

meshop.getFacesUsingVert <Mesh mesh> <vertlist>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that use the specified vertices.

meshop.getHiddenFaces <Mesh mesh>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are hidden.

meshop.getNumFaces <Mesh mesh>

Returns the number of faces in the mesh.

meshop.getVertsUsedOnlyByFaces <Mesh mesh> <facelist>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices used by the specified faces.

meshop.makeFacesPlanar <Mesh mesh> <facelist>

Moves the specified faces so that they are planar.

meshop.removeDegenerateFaces <Mesh mesh>

Deletes any degenerate faces in the mesh. A degenerate face has two or more equal vertex indices.

meshop.removeIllegalFaces <Mesh mesh>

Deletes any illegal faces in the mesh. An illegal face has one or more vertex indices that are out of range.

meshop.setHiddenFaces <Mesh mesh> <facelist>

Sets the specified faces as hidden, and non-specified faces as visible.

meshop.setNumFaces <Mesh mesh> <int>

Sets the number of faces in the mesh.

Mesh methods

meshop.createPolygon <Mesh mesh> <vertIndex array> smGroup:<int=0> matID:<int=1>

Creates a set of faces using the specified vertices. The order of the vertices in the faces is the order in the vertex array. The polygon may be nonconvex, but should be (roughly) coplanar.

<smGroup> and <matID> specify the smoothing group data and material ID number assigned to the new faces.

meshop.cut <Mesh mesh> <int edge1Index> <float edge1f> <int edge2Index> <float edge2f> <point3 normal> fixNeighbors:<boolean=true> split:<boolean=true> node:<node=unsupplied>

Cuts the mesh from a point on one edge to a point on another, along a line drawn by looking at the mesh from a particular viewpoint.

<edge1Index> specifies the edge that the cut starts on.

<edge1f> specifies the fractional distance along the edge to start the cut from.

<edge2Index> specifies the edge that the cut ends on.

<edge2f> specifies the fractional distance along the edge to finish the cut on.

<normal> specifies the direction of view. The cut will take place on this "side" of the mesh, in the plane formed by this vector and the direction from the start to the end.

If <fixNeighbors> is true, the faces on the other side of each end of the cut should be split to prevent splits at the ends. If <split> is true, the cut will split the mesh apart. If false, the cut will just refine the mesh by adding geometry. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the normal is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the normal is in the mesh's local coordinate system.

meshop.getPolysUsingVert <Mesh mesh> <vertlist> ignoreVisEdges:<boolean=false> threshhold:<float=45.>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are in 'polygons' containing the specified vertices. The definition of a polygon is all faces sharing invisible edges with edge angles below the threshhold angle. The default threshhold angle is 45 degrees. If ignoreVisEdges is set to true, the edge visibility is ignored but the threshhold is still relevant.

meshop.optimize <Mesh mesh> <float normalThreshold> <float edgeThreshold> <float bias> <float maxEdge> saveMatBoundries:<boolean=true> saveSmoothBoundries:<boolean=true> autoEdge:<boolean=true>

Reduces the mesh in complexity by reducing the number of faces based on a surface normal threshold. Adjacent faces whose difference in surface normal angle falls below <normalThreshold> will be collapsed into a single triangle. If <autoEdge> is true, when the angle between adjacent surface normals is less than <edgeThreshold> the edge will be invisible. When optimizing mesh objects, as the optimization increases, you can get lots of long skinny 'degenerate' triangles (that cause rendering artifacts). Increasing <bias> keeps triangles from becoming degenerate. The range of values is from 0 to 1 (where 0 turns bias off). Values close to 1 reduce the amount of optimization in favor of maintaining equilateral triangles. A <maxEdge> value > 0 will prevent the optimize function from creating edges longer than this value. If this parameter is <=0 no limit is placed on the length of the edges. If <saveMatBoundries> is true, faces won't be collapsed across a material boundary. If <saveSmoothBoundries> is true, faces won't be collapsed across a dissimilar smoothing group boundary.

meshop.slice <Mesh mesh> <facelist> <point3 normal> <float offset> separate:<boolean=false> delete:<boolean=false> node:<node=unsupplied>

Slices the mesh along the specified slicing plane. The slicing plane is defined as all points which, when DotProd'd with <normal>, return <offset>. <normal> should be normalized.

<separate> specifies whether the slice should separate the mesh into two separate elements (true) or just refine the existing mesh by splitting faces (false).

<delete> specifies whether the slice should remove the portion of the mesh "below" the slicing plane, where "below" is defined as the area where DotProd (p,<normal>) - <offset> < 0. If <delete> is true, <separate> is ignored. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the normal is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the normal is in the mesh's local coordinate system.

copy <trimesh>

Yields a copy of the source TriMesh.

delete <trimesh>

Clears out the TriMesh's geometry and topology, effectively freeing its memory.

The following method is not applicable to TriMeshes:

animateVertex <mesh> <vertex_spec>

Applies controllers to the specified vertices of the Editable_Mesh, where <vertex_spec> is one of:

<integer_index>

<integer_index_array>

#all

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 and Scripting Vertex and Control Point Animation for details on accessing the Editable_Mesh vertices. The controller values assigned to the vertices is in object space. See Using Node Transform Properties for information on converting between world space to object space.

The setMesh() method enables bulk changes to a mesh via arrays of vertices, faces, tverts, etc. setMesh() has the following forms:

setMesh <mesh> [ numverts:<integer> ] [ numfaces:<integer> ]

Resets the mesh to the given geometry but with no topology (i.e., no faces or edges). Any current mesh data is lost. You have to individually place the vertices and create the faces from the vertices. The default number of vertices and faces are 36 and 50, respectively.

setMesh <mesh> [ vertices:<array_of_point3s> ] \

[ faces:<array_of_point3s> ] \

[ materialIDs:<array_of_integers> ] \

[ tverts:<array_of_point3s> ]

Resets the mesh based on the given arrays. Only those portions of the mesh that are specified are reset. For example, if only the vertices parameter is specified, the existing face data is retained. Each Point3 value in the vertices array specifies the position of the vertex in the current coordinate system. Each Point3 value in the faces array specifies the 3 vertex indices that form the face. The materialIDs array specifies the material ID to be assigned to each face. Each Point3 value in the tverts array specifies the UVW coordinates of the texture vertices. See Texture Mapping in the methods section for more information on texture vertices.

setMesh <mesh> [ length:<integer> ] [ width:<integer> ] [ lengthsegs:<integer> ] \

[ widthhsegs:<integer> ]

Resets the mesh with a flat rectangular mesh with the given size and number of segments. The default length and width are 50, the default number of segments is 5.

setMesh <mesh> <trimesh>

Sets the mesh to a copy of the source TriMesh.

Mapping methods – General

meshop.deleteIsoMapVertsAll <Mesh mesh>

For all mapping channels, deletes all mapping vertices that are not used by a mapping face.

meshop.freeMapChannel <Mesh mesh> <int mapChannel>

Deletes the map vertex and face arrays for the specified channel, and sets their count to 0.

meshop.getMapFacesUsingMapVert <Mesh mesh> <int mapChannel> <mapVertlist>

Returns a bitarray of size=(#map faces for channel in mesh) with bits set for all map faces that use the specified map vertices.

meshop.getMapVertsUsingMapFace <Mesh mesh> <int mapChannel> <mapFacelist>

Returns a bitarray of size=(#map vertices for channel in mesh) with bits set for all map vertices that use the specified map faces.

meshop.setFaceAlpha <Mesh mesh> <int mapChannel> <facelist> <float alpha>

For the specified map channel, sets the map vertex color to value between 0 (transparent) and 1 (opaque) for the map vertices used by the map faces associated with the specified faces.

meshop.setFaceColor <Mesh mesh> <int mapChannel> <facelist> <color color>

For the specified map channel, sets the map vertex color to <color> for the map vertices used by the map faces associated with the specified faces.

meshop.setVertAlpha <Mesh mesh> <int mapChannel> <vertlist> <float alpha>

For the specified map channel, sets the map vertex color to a value between 0 (transparent) and 1 (opaque) for the map vertices associated with the specified mesh vertices.

meshop.setVertColor <Mesh mesh> <int mapChannel> <vertlist> <color color>

For the specified map channel, sets the map vertex color to <color> for the specified map vertices.

meshop.setNumMaps <Mesh mesh> <int count> keep:<boolean=false>

Sets the number of map channels available. The number of map channels can be set from 2 to 100. Map channels 1 and 2 are the Vertex Color and default Texture Map channels. If keep is false, the old mapping information is discarded. If true, the old mapping information is retained after the resize.

meshop.getNumMaps <Mesh mesh>

Returns the number of map channels available as an <integer>.

meshop.setMapSupport <Mesh mesh> <Integer mapChannel> <Boolean support>

Sets whether the specified mapping channel is supported or not. If support is true, and the channel support state is currently false, a new map face array of the same size as the number of faces in the mesh is allocated, but no map vertex array is allocated. If support is false, and the channel support state is currently true, existing map channel face and vertex arrays are deallocated. If support and the current channel support state are both the same, no action is performed. SetNumMaps() is automatically called if the specified map channel is not available.

mapChannel index values are 0-based, with Map channels 0 and 1 being the Vertex Color and default Texture Map channels.

meshop.getMapSupport <Mesh mesh> <Integer mapChannel>

Returns whether the specified map channel is supported. This signifies that a map face array is present, but not necessarily a map vertex array.

meshop.setNumMapVerts <Mesh mesh> <Integer mapChannel> <Integer count> keep:<boolean=FALSE>

Sets the number of vertices for the map channel, initializing the map vertex array. If keep is false or not specified, the old map vertex information is discarded. If true, the old map vertex information is retained after the resize.

meshop.getNumMapVerts <Mesh mesh> <Integer mapChannel>

Returns the number of vertices for the map channel as an <integer>.

meshop.setNumMapFaces <Mesh mesh> <Integer mapChannel> <Integer count> keep:<boolean=false> keepCount:<int=0>

Sets the number of faces for the map channel. If keep is false or not specified, the old map face information is discarded. If true, the old map face information from the number of faces specified by keepCount is retained after the resize. Dangerous to use with map channels 0 and 1, so miminum mapChannel value is 2.

meshop.getNumMapFaces <Mesh mesh> <Integer mapChannel>

Returns the number of faces for the map channel as an <integer>.

meshop.setMapVert <Mesh mesh> <Integer mapChannel> <Integer index> <Point3 xyz>

Sets the coordinates of the specified map vertex.

meshop.getMapVert <Mesh mesh> <Integer mapChannel> <Integer index>

Returns the coordinates of the specified map vertex as a <point3>.

meshop.setMapFace <Mesh mesh> <Integer mapChannel> <Integer index> <Point3 face>

Sets the map vertices for the specified map face.

meshop.getMapFace <Mesh mesh> <Integer mapChannel> <Integer index>

Returns the vertices of the specified map face as a <point3>.

meshop.makeMapPlanar <Mesh mesh> <Integer mapChannel>

Applies a simple planar mapping to the specified channel. This is done by copying the mesh topology and vertex locations into the map, resizing the face and vertex arrays if necessary.

meshop.getIsoMapVerts <Mesh mesh> <Integer mapChannel>

Returns a <bitarray> with a bit set for each isolated map vertex (unrefereced by any map face) for the specified channel.

meshop.deleteMapVertSet <Mesh mesh> <Integer mapChannel> {<BitArray set> | <Integer index> | <integer array>}

Deletes the specified map vertices. Returns a <bitarray> with a bit set for each map face that used one of the deleted map vertices. Normally, you should delete or modify the map faces using the map vertices before deleting the map vertices, as after the vertex deletion you can't tell which vertex on a face was a vertex that was deleted.

meshop.freeMapVerts <Mesh mesh> <Integer mapChannel>

Deallocates the map vertex array and sets the number of map vertices to 0.

meshop.freeMapFaces <Mesh mesh> <Integer mapChannel>

Deallocates the map face array and sets the number of map faces to 0.

meshop.applyUVWMap <TriMesh mesh> {<#planar | #cylindrical | #spherical | #ball | #box> | <#face>} \ utile:<float=1.0> vtile:<float=1.0> wtile:<float=1.0> uflip:<boolean=false> vflip:<boolean=false> wflip:<boolean=false> cap:<boolean=true> tm:<Matrix3=identity matrix>

channel:<int=1>

Applies the specified mapping type to the mapping channel.

utile/vtile/wtile - Number of tiles in the U/V/W directions.

uflip/vflip/wflip - U/V/W are mirrored if true.

cap - used with #cylindrical. If true, then any face normal that is pointing more vertically than horizontally will be mapped using planar coordinates.

tm - defines the mapping space. As each point is mapped, it is multiplied by this matrix, and then it is mapped.

channel - the mapping channel the mapping is applied to, defaults to channel 1.

meshop.buildMapFaces <Mesh mesh> <Integer mapChannel> <Boolean keep>

Sets the number of map faces to the number of mesh faces, retaining existing mapping data if keep is true. Deletes any map vertices that are not used by the map faces.

meshop.defaultMapFaces <Mesh mesh> <Integer mapChannel> <Integer count>

Sets the number of map faces to the number of mesh faces, and the number of map vertices to the number of mesh vertices. The map face vertices are set to the same vertex index as the corresponding mesh face vertices (i.e., there will be a 1-to-1 correspondence between map faces/vertices and the mesh faces/vertices). The map vertex UVW coordinates are set to the normalized (0 to 1) position of the corresponding mesh vertex in the mesh's bounding box.

Mapping methods – Color per vertex channel (Channel 0)

meshop.getNumCPVVerts <Mesh mesh>

Returns the number of Color Per Vertex mapping channel vertices.

meshop.setNumCPVVerts <Mesh mesh> <int>

Sets the number of Color Per Vertex mapping channel vertices.

Mapping methods – Default texture mapping channel (Channel 1)

meshop.getNumTVerts <Mesh mesh>

Returns the number of Default Texture mapping channel vertices.

meshop.setNumTVerts <Mesh mesh> <int>

Sets the number of Default Texture mapping channel vertices.

Data methods – Vertex selection weight channel (Channel 1)

meshop.getVSelectWeight <Mesh mesh> <int vertIndex>

Returns the Vertex Selection Weight data value for the specified vertex.

meshop.setVSelectWeight <Mesh mesh> <vertlist> <float weight>

Sets the Vertex Selection Weight data value for the specified vertex.

meshop.resetVSelectWeights <Mesh mesh>

Sets the Vertex Selection Weight data value to 1.0 for all vertices.

meshop.supportVSelectWeights <Mesh mesh>

Enables support of the Vertex Selection Weight channel.

meshop.freeVSelectWeights <Mesh mesh>

Deletes (deallocates) the Vertex Selection Weight data array.

Data methods – Vertex weight channel (Channel 2)

meshop.getVertWeight <Mesh mesh> <int vertIndex>

Returns the Vertex Weight data value for the specified vertex.

meshop.setVertWeight <Mesh mesh> <vertlist> <float weight>

Sets the Vertex Weight data value for the specified vertex.

meshop.resetVertWeights <Mesh mesh>

Sets the Vertex Weight data value to 1.0 for all vertices.

meshop.supportVertWeights <Mesh mesh>

Enables support of the Vertex Weight channel.

meshop.freeVertWeights <Mesh mesh>

Deletes (deallocates) the Vertex Weight data array.

Data methods – Vertex Alpha channel (Channel 3)

meshop.getVAlpha <Mesh mesh> <int vertIndex>

Returns the Vertex Alpha data value for the specified vertex.

meshop.setVAlpha <Mesh mesh> <vertlist> <float alpha>

Sets the Vertex Alpha data value for the specified vertex.

meshop.resetVAlphas <Mesh mesh>

Sets the Vertex Alpha data value to 1.0 for all vertices.

meshop.supportVAlphas <Mesh mesh>

Enables support of the Vertex Alpha channel.

meshop.freeVAlphas <Mesh mesh>

Deletes (deallocates) the Vertex Alpha data array.

Data methods – Vertex corner channel (Channel 4)

meshop.getVertCorner <Mesh mesh> <int vertIndex>

Returns the Vertex Corner data value for the specified vertex.

meshop.setVertCorner <Mesh mesh> <vertlist> <float weight>

Sets the Vertex Corner data value for the specified vertex.

meshop.resetVertCorners <Mesh mesh>

Sets the Vertex Corner data value to 0.0 for all vertices.

meshop.supportVertCorners <Mesh mesh>

Enables support of the Vertex Corner channel.

meshop.freeVertCorners <Mesh mesh>

Deletes (deallocates) the Vertex Corner data array.

Editable mesh UI property methods

meshop.getAffectBackfacing <Mesh mesh> -- editable mesh only

meshop.setAffectBackfacing <Mesh mesh> <boolean> -- editable mesh only

meshop.getBubble <Mesh mesh> -- editable mesh only

meshop.setBubble <Mesh mesh> <float> -- editable mesh only

meshop.getDisplacementMapping <Mesh mesh> -- editable mesh only

meshop.setDisplacementMapping <Mesh mesh> <boolean> -- editable mesh only

meshop.getExtrusionType <Mesh mesh> -- editable mesh only

meshop.setExtrusionType <Mesh mesh> <int> -- editable mesh only

meshop.getFalloff <Mesh mesh> -- editable mesh only

meshop.setFalloff <Mesh mesh> <float> -- editable mesh only

meshop.getIgnoreBackfacing <Mesh mesh> -- editable mesh only

meshop.setIgnoreBackfacing <Mesh mesh> <boolean> -- editable mesh only

meshop.getIgnoreVisEdges <Mesh mesh> -- editable mesh only

meshop.setIgnoreVisEdges <Mesh mesh> <boolean> -- editable mesh only

meshop.getNormalSize <Mesh mesh> -- editable mesh only

meshop.setNormalSize <Mesh mesh> <float> -- editable mesh only

meshop.getPinch <Mesh mesh> -- editable mesh only

meshop.setPinch <Mesh mesh> <float> -- editable mesh only

meshop.getPlanarThreshold <Mesh mesh> -- editable mesh only

meshop.setPlanarThreshold <Mesh mesh> <float> -- editable mesh only

meshop.getSelByVertex <Mesh mesh> -- editable mesh only

meshop.setSelByVertex <Mesh mesh> <boolean> -- editable mesh only

meshop.getShowFNormals <Mesh mesh> -- editable mesh only

meshop.setShowFNormals <Mesh mesh> <boolean> -- editable mesh only

meshop.getShowVNormals <Mesh mesh> -- editable mesh only

meshop.setShowVNormals <Mesh mesh> <boolean> -- editable mesh only

meshop.getSoftSel <Mesh mesh> -- editable mesh only

meshop.setSoftSel <Mesh mesh> <boolean> -- editable mesh only

meshop.getSplitMesh <Mesh mesh> -- editable mesh only

meshop.setSplitMesh <Mesh mesh> <boolean> -- editable mesh only

meshop.getSSEdgeDist <Mesh mesh> -- editable mesh only

meshop.setSSEdgeDist <Mesh mesh> <int> -- editable mesh only

meshop.getSSUseEdgeDist <Mesh mesh> -- editable mesh only

meshop.setSSUseEdgeDist <Mesh mesh> <boolean> -- editable mesh only

meshop.getSubdivisionAngle <Mesh mesh> -- editable mesh only

meshop.setSubdivisionAngle <Mesh mesh> <float> -- editable mesh only

meshop.getSubdivisionDisplacement <Mesh mesh> -- editable mesh only

meshop.setSubdivisionDisplacement <Mesh mesh> <boolean> -- editable mesh only

meshop.getSubdivisionDistance <Mesh mesh> -- editable mesh only

meshop.setSubdivisionDistance <Mesh mesh> <float> -- editable mesh only

meshop.getSubdivisionEdge <Mesh mesh> -- editable mesh only

meshop.setSubdivisionEdge <Mesh mesh> <float> -- editable mesh only

meshop.getSubdivisionMaxLevels <Mesh mesh> -- editable mesh only

meshop.setSubdivisionMaxLevels <Mesh mesh> <int> -- editable mesh only

meshop.getSubdivisionMaxTriangles <Mesh mesh> -- editable mesh only

meshop.setSubdivisionMaxTriangles <Mesh mesh> <int> -- editable mesh only

meshop.getSubdivisionMethod <Mesh mesh> -- editable mesh only

meshop.setSubdivisionMethod <Mesh mesh> {#regular | #spatial | #curvature | #spatialAndCurvature} -- editable mesh only

meshop.getSubdivisionMinLevels <Mesh mesh> -- editable mesh only

meshop.setSubdivisionMinLevels <Mesh mesh> <int> -- editable mesh only

meshop.getSubdivisionSteps <Mesh mesh> -- editable mesh only

meshop.setSubdivisionSteps <Mesh mesh> <int> -- editable mesh only

meshop.getSubdivisionStyle <Mesh mesh> -- editable mesh only

meshop.setSubdivisionStyle <Mesh mesh> {#tree | #grid | #delaunay} -- editable mesh only

meshop.getSubdivisionView <Mesh mesh> -- editable mesh only

meshop.setSubdivisionView <Mesh mesh> <boolean> -- editable mesh only

meshop.getWeldPixels <Mesh mesh> -- editable mesh only

meshop.setWeldPixels <Mesh mesh> <int> -- editable mesh only

meshop.getWeldThreshold <Mesh mesh> -- editable mesh only

meshop.setWeldThreshold <Mesh mesh> <float> -- editable mesh only

Vertex Methods

getNumVerts <mesh>

Returns number of vertices as an integer, equivalent to using <mesh>.numverts

setNumVerts <mesh> <vert_index_integer> [ <boolean> ]

Set the number of vertices as specified. If the optional boolean argument is true, the existing topology remains intact. If it is false or left off, the topology is lost.

getVert <mesh> <vert_index_integer>

Returns the position (in the current working coordinate system) of the indexed vertex as a point3

setVert <mesh> <vert_index_integer> ( <point3> | <float> <float> <float> )

Sets the position coordinates of the indexed vertex as a point3 value, or 3 floats - X,Y,Z

deleteVert <mesh> <vert_index_integer>

Deletes the indexed vertex from the mesh and all faces that share the vertex. Renumbers vertices and faces to account for the deletions. Also adjusts face vertex indexes as necessary.

getNormal <mesh> <vert_index_integer>

Returns the normal at the indexed vertex's position as a point3. The normal is based on the faces that use the vertex and the smoothing groups assigned to those faces.

setNormal <mesh> <vert_index_integer> <point3>

Sets the indexed vertex's normal vector

getVertSelection <node> [ <modifier_or_index> ] [ name:<name> ]

getVertSelection <mesh>

Returns the current vertex selection set, or the specified named selection set if the optional name: parameter is specified, as a BitArray. The optional <modifier_or_index> identifies the Edit Mesh or Mesh Select modifier on the given scene object from which the selection BitArray is obtained. For example:

getVertSelection $foo $foo.modifiers[3]

If the optional <modifier_or_index> argument is not supplied, the <node> must be an Editable Mesh object and the selection is taken from the base object. If <modifier_or_index> is supplied, it must be either a modifier on the node or a number. If it is a modifier, it must be either an Edit Mesh or a Mesh Select modifier. If it is a number, it is used as an index into the Edit Mesh/Select Modifiers on the <node> starting from the top of the stack. Note that this index does not count any other types of modifier present. So, an index of 1 will always get the selection currently active at the top of the stack.

The function returns a BitArray that are the 1-based indexes of the vertices currently selected, or the vertices specified by the named selection set, in the object by the given modifier. For example:

getVertSelection $foo $foo.modifiers[3]

yields

#{2..5,9,25..27}

This is a snapshot of the selection—the BitArray doesn't change automatically as you make different selections. Further, it reflects the current vertex selection whether or not the modifier is in vertex sub-object selection mode (this selection is remembered and re-established whenever you go back into vertex subobject mode). So, for example, if you select some vertices then click out of vertex subobject mode, the whole object rather than the selection is passed up the stack to the next modifier, but getVertSelection() returns the selected vertices at the time the subobject mode was exited.

You might use the modifiers modifier array accessing scheme here if you've got many edit mesh modifiers with non-unique names. You can also use a constructed string as an index into the modifiers array, for example:

$foo.modifiers["edit mesh" + i as string]

assuming the variable 'i' had some indexing value and the names were set up thusly. '+' on strings concatenates.

setVertSelection <node> [ <modifier_or_index> ] \

( <sel_bitarray> | <sel_array> ) \

[ name:<name> ] [ keep:<boolean> ]

setVertSelection <mesh> ( <sel_bitarray> | <sel_array> ) \

[ keep:<boolean> ]

Sets the vertex selections in an Editable Mesh base object, Mesh Select modifier, Edit Mesh Modifier, or TriMesh. This mirrors the selection getting method above.

The <modifier_or_index> argument is interpreted as for the get- form above, except that only the Mesh Select modifier is supported for set operations.

For example:

setVertSelection $foo #{1..4,100..102}

setFaceSelection $foo \

(getFaceSelection $baz) keep:true

If the optional name: argument is specified, the vertices in the specified named selection set in the Editable Mesh or Mesh Select modifier are selected. If the name: argument is not specified, the selection index argument gives the indexes of the sub-object items to be selected as either a BitArray or an array of integers. If the optional keep: keyword argument is false or not supplied, any current selection will be replaced by the new one. If the keep: keyword argument is true, the new selection is added to the current selection. The name: argument is not applicable to TriMeshes.

Use the mesh update() function after making a group of selection changes in order to make them visible to any modifiers on the object.

averageSelVertCenter <node> [ <modifier_or_index> ]

Returns the average position (center) of the selected vertices in the given mesh as a Point3. If the object is not a mesh this method returns undefined. If no vertices are selected in the mesh, a value of [0,0,0] is returned. This method is not applicable to TriMeshes.

The <modifier_or_index> argument is interpreted as for getVertSelection.

averageSelVertNormal <node> [ <modifier_or_index> ]

Returns the normalized average of the normals of the selected vertices in the given mesh as a Point3. If the given node is not a mesh, it returns undefined. If no vertices are selected in the mesh, or the averaged normal is [0,0,0], a value of [1,0,0] is returned. This method is not applicable to TriMeshes.

The <modifier_or_index> argument is interpreted as for getVertSelection.

The vertex normals used in this method do not consider smoothing group data of the faces that use the vertex.

Face Methods

getNumFaces <mesh>

Returns number of faces as an integer, equivalent to using <mesh>.numfaces

getFace <mesh> <face_index_integer>

Returns the face vertex indexes for the indexed face as a point3. Each component of the point3 value contains a vertex index.

setFace <mesh> <face_index_integer> <vert_indices_point3>

Sets the face vertex indexes for the indexed face from a point3.

setFace <mesh> <face_index_integer> <vert_index_integer> \

<vert_index_integer> <vert_index_integer>

Sets the face vertex indexes for the indexed face from 3 vertex indexes.

deleteFace <mesh> <face_index_integer>

Deletes indexed face from the mesh. Renumbers faces accordingly.

collapseFace <mesh> <face_index_integer>

Deletes indexed face from the mesh, welding its 3 vertices together at the center of the original face. Renumbers faces accordingly.

getFaceNormal <mesh> <face_index_integer>

Returns the normal of the indexed face as a point3.

setFaceNormal <mesh> <face_index_integer> <point3>

Sets the indexed face's normal vector. As soon as you run update() on the mesh, this value is overwritten.

getFaceMatID <mesh> <face_index_integer>

Returns the indexed face's material ID as an integer.

setFaceMatID <mesh> <face_index_integer> <integer>

Sets the indexed face's material ID.

getFaceSmoothGroup <mesh> <face_index_integer>

Returns the indexed face's smoothing groups as a 32-bit integer. There are 32 possible smoothing groups. Each bit in the returned value corresponds to a smoothing group. If a bit is turned on, the face is part of that smoothing group. You can retrieve the list of smoothing groups for a face as a BitArray using the following function:

fn getfacesmoothgroupB obj face =

(

local sgroup_val=getfacesmoothgroup obj face

local sg_bitarray=#{}

if sgroup_val < 0 do

(

sg_bitarray[32]=true

sgroup_val -= 2^31

)

for i = 1 to 31 do

(

sg_bitarray[i]= (mod sgroup_val 2 > .5)

sgroup_val /= 2

)

sg_bitarray

)

setFaceSmoothGroup <mesh> <face_index_integer> <smoothing_group_integer>

Sets the indexed face's smoothing groups. If you have a face's desired smoothing groups as a BitArray, you could set the face's smoothing group data using the following function:

fn setfacesmoothgroupB obj face sg_bitarray =

(

local sgroup_val=0

for i in sg_bitarray do sgroup_val += 2^(i-1)

setfacesmoothgroup obj face sgroup_val

update obj

)

getFaceSelection <node> [ <modifier_or_index> ] [ name:<name> ]

getFaceSelection <mesh>

Retrieves the face selection set, or the specified named selection set if the optional name: parameter is specified, as a BitArray. See the getVertSelection() method for more information.

setFaceSelection <node> [ <modifier_or_index> ] \

( <sel_bitarray> | <sel_array> ) \

[ name:<name> ] [ keep:<boolean> ]

setFaceSelection <mesh> ( <sel_bitarray> | <sel_array> ) \

[ keep:<boolean> ]

Sets the face selections in an Editable Mesh base object, Mesh Select modifier, Edit Mesh modifier, or TriMesh. This mirrors the selection getting method above. See the setVertSelection() method for more information.

deselectHiddenFaces <mesh>

deselects the hidden faces in the mesh. This method is not applicable to TriMeshes.

extrudeFace <mesh> ( <index> | <bitarray> | <integer_array> | #selection ) \

<amount> <scale> \

[ dir:(<point3> | #common | #independent ) ]

Provides capabilities equivalent to the Extrude Face modifier. This function works only on Editable Mesh nodes. The second argument defines which faces to extrude, either a single face index, a BitArray of face indexes, an integer array of face indexes, or the name literal #selection meaning the current face selection in the Editable Mesh. The <amount> argument specifies the extrude distance and the <scale> specifies a % amount to scale each face cluster.

If the optional dir: keyword argument is not specified, face clusters are extruded by moving their vertices independently along the average normal at each vertex, as does the Extrude Face modifier. If it is specified, it can be a point3 giving a direction vector in which all vertices are moved, or it can be the value #independent which is the same as the default direction, or it can be the value #common which extrudes face clusters along the average normal of all the face normals in each cluster. #common is equivalent to the Group Normal option in EditableMesh, and #independent is equivalent to the Local Normal option. An example usage is:

s=sphere()

extrudeface s #{1..20} 10 100 dir:#independent

update s

meshop.getVertsUsingFace <Mesh mesh> <facelist>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are used by the specified faces.

meshop.getEdgesUsingFace <Mesh mesh> <facelist>

Returns a bitarray of size=(#edges in mesh) with bits set for all edges that are used by the specified faces.

meshop.getPolysUsingFace <Mesh mesh> <facelist> ignoreVisEdges:<boolean=false> threshhold:<float=45.>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are in 'polygons' containing the specified faces. The definition of a polygon is all faces sharing invisible edges with edge angles below the threshhold angle. The default threshhold angle is 45 degrees. If ignoreVisEdges is set to true, the edge visibility is ignored but the threshhold is still relevant.

meshop.autoSmooth <Mesh mesh> <facelist> <float threshold>

Smooths the specified faces based on the threshold angle.

meshop.unifyNormals <Mesh mesh> <facelist>

Unifies the normals of the specified faces.

meshop.flipNormals <Mesh mesh> <facelist>

Flips the normal of the specified faces.

<float> meshop.getFaceArea <Mesh mesh> <facelist>

Returns the area of the specified faces as a <float>.

Edge Methods

getEdgeVis <mesh> <face_index_integer> <edge_index_integer>

Returns the edge visibility for given edge (1,2,3) on indexed face as a boolean.

setEdgeVis <mesh> <face_index_integer> <edge_index_integer> <boolean>

Sets the edge visibility for given edge (1,2,3) on indexed face.

getEdgeSelection <node> [ <modifier_or_index> ] [ name:<name> ]

getEdgeSelection <mesh>

Retrieves the edge selection set, or the specified named selection set if the optional name: parameter is specified, as a BitArray. See the getVertSelection() method for more information.

setEdgeSelection <node> [ <modifier_or_index> ] \

( <sel_bitarray> | <sel_array> ) \

[ name:<name> ] [ keep:<boolean> ]

setEdgeSelection <mesh> ( <sel_bitarray> | <sel_array> ) \

[ keep:<boolean> ]

Sets the edge selections in an Editable Mesh base object, Mesh Select modifier, Edit Mesh Modifier, or TriMesh. This mirrors the selection getting method above. See the setVertSelection() method for more information.

deselectHiddenEdges <mesh>

Deselects the hidden edges in the mesh. This method is not applicable to TriMeshes.

meshop.getVertsUsingEdge <Mesh mesh> <edgelist>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are used by the specified edges.

meshop.getFacesUsingEdge <Mesh mesh> <edgelist>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that use the specified edges.

meshop.getPolysUsingEdge <Mesh mesh> <edgelist> ignoreVisEdges:<boolean=false> threshhold:<float=45.>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are in 'polygons' containing the specified edges. The definition of a polygon is all faces sharing invisible edges with edge angles below the threshhold angle. The default threshhold angle is 45 degrees. If ignoreVisEdges is set to true, the edge visibility is ignored but the threshhold is still relevant.

meshop.getEdgesReverseEdge <Mesh mesh> <edgelist>

Returns a bitarray of size=(#edges in mesh) with bits set for all additional edges that use the same vertices as the specified edges. These are edges on the adjacent faces.

Example:

Plane length:100 width:100 isSelected:on

convertTo $ TriMeshGeometry

max modify mode

subobjectLevel = 1

select $.verts[13]

-- get edges that use vertex 13

edges = meshop.getEdgesUsingVert $ (getVertSelection $)

-- select the vertices used by those edges

$.selectedVerts = meshop.getVertsUsingEdge $ edges

update $

-- not what we wanted, really want all vertices "surrounding" vertex 13

faces = meshop.getPolysUsingVert $ 13

$.selectedVerts = meshop.getVertsUsingFace $ faces

update $

-- or ...

faces = meshop.getFacesUsingVert $ #(13)

edges = meshop.getEdgesUsingFace $ faces

-- turn off all visible edges

for e in edges do edges[e]=not (getEdgeVis $ (1+(e-1)/3)(1+mod (e-1) 3))

-- get the edges on the adjacent faces that are the "reverse" of these edges

-- "OR" that bitarray with the initial edges bitarray

edges = (meshop.getEdgesReverseEdge $ edges) + edges

-- get the faces that use the edges, and "OR" that bitarray with the initial

-- face bitarray

faces = (meshop.getFacesUsingEdge $ edges) + faces

$.selectedVerts = meshop.getVertsUsingFace $ faces

update $

meshop.autoEdge <Mesh mesh> <edgelist> <float threshold> type:<{#SetClear | #Set | #Clear}=#SetClear>

Sets/clears the edge visibility for the specified edges based on the threshold angle. Note: for an edge to be autoEdged, both it and the "reverse" edge on the face sharing the edge vertices must be specified in the edge specification.

Notes

3ds max defines an edge as the edge of a face. In any mesh object, the number of edges is 3 times the number of faces. A face has 3 vertices, and the face edges connect these vertices. Edges 1, 2, and 3 are the edges between vertices 1 and 2, 2 and 3, and 3 and 1, respectively. The first edge in a mesh is edge 1 on face 1, and the last edge is edge 3 on the last face. The following script selects all of the visible edges in the specified mesh:

EdgeSelSet=#()

for face = 1 to obj.numfaces do

for edge = 1 to 3 do

if (getedgevis obj face edge) then

append EdgeSelSet (((face-1)*3)+edge)

setedgeselection obj EdgeSelSet

update obj

The following function returns the indices of the 2 vertices that define an edge as a Point2 value. The two arguments to the function are a editable mesh node or TriMesh value and the edge index. A value of undefined is returned if the first argument isn't an editable mesh node or TriMesh value, or if the edge index is out of range.

fn edgeVerts theObj theEdge =

(

if not (classof theObj == Editable_mesh or

classof theObj == triMesh) do return undefined

if theEdge < 1 or theEdge > (theObj.numfaces*3) do return undefined

local theFace = ((theEdge-1)/3)+1

local theVerts = getFace theObj theFace

case ((mod (theEdge-1) 3) as integer) of

(

0: point2 theVerts.x theVerts.y

1: point2 theVerts.y theVerts.z

2: point2 theVerts.z theVerts.x

)

)

Texture Vertex Methods

getNumTVerts <mesh>

Returns number of texture vertices as an integer, equivalent to using <mesh>.numtverts

setNumTVerts <mesh> <number> [ <boolean> ]

Sets the number of texture vertices as specified. If the optional boolean argument is true, the existing topology remains intact. If it is false or not supplied, the topology is lost.

getTVert <mesh> <tvert_index_integer>

Returns the UVW coordinates of the indexed texture vertex

setTVert <mesh> <tvert_index_integer> ( <point3> | <x> <y> <z> )

Sets the UVW coordinates of the indexed texture vertex as a point3 value, or 3 floats - U,V,W

getTVFace <mesh> <face_index_integer>

setTVFace <mesh> <face_index_integer> <vert_indices_point3>

setTVFace <mesh> <face_index_integer> <tvert_index_integer> \

<tvert_index_integer> <tvert_index_integer>

The getTVFace() and setTVFace() functions mirror the getFace() and setFace() functions and are used to specify texture mapping topology in terms of texture vertices. You can set up and access texture vertices with the getTVert(), setTVert(), getNumTVerts(), and setNumTVerts() functions described above.

buildTVFaces <mesh> [ <boolean> ]

The buildTVFaces() function only needs to be called on meshes you are adding texture vertices to yourself to create the internal texture face array. Meshes that 3ds max applies mapping coordinates to maintain the TVFace array automatically. This is not done automatically when you add texture vertices to meshes yourself so you need to call buildTVFaces() explicitly whenever you change the texture vertex count, and before you construct the texture faces. If the optional boolean argument is true, the existing texture mapping remains intact. If it is false or not supplied, the existing texture mapping is lost (all texture faces are rebuilt, with all three vertices of the texture face using texture vertex 1).

numMapsUsed <mesh>

Returns the an upper limit on the number of texture map channels used by the given node. This is at least 1+(highest channel in use). This method is used so a script that does something to all map channels doesn't always have to do it to every channel up to 99 (the highest possible texture map channel), but rather only to this value. This method is not applicable to TriMeshes.

Notes

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 Working with Editable Meshes.

The texture vertex methods do not support multiple mapping channels in 3ds max 4.

Color-Per-Vertex Methods

getNumCPVVerts <mesh>

Returns number of color-per-vertex vertices as an integer, equivalent to using <node>.numcpvverts

setNumCPVVerts <mesh> <integer> [ <boolean> ]

Sets the number of c-p-v vertices. If the optional boolean argument is true, the existing topology remains intact. If it is false or not supplied, the topology is lost.

buildVCFaces <mesh> [ <boolean> ]

Builds the c-p-v face array after you have set the c-p-v vertex count. If the optional boolean argument is true, the existing topology remains intact. If it is false or not supplied, the topology is lost.

defaultVCFaces <mesh>

Sets the number of c-p-v vertices and c-p-v faces to match exactly the current mesh's geometry and topology and calls buildVCFaces()

getVertColor <mesh> <CPVvert_index_integer>

Returns the color of the indexed c-p-v vertex as a color

getVCFace <mesh> <CPVface_index_integer>

Returns the topology for the indexed c-p-v face as a point3 containing 3 c-p-v vertex indexes

setVCFace <mesh> <CPVface_index_integer> <CPVvert_indices_point3>

Sets the indexed c-p-v face topology from a point3 containing 3 c-p-v vertex indexes

setVCFace <mesh> <CPVface_index_integer> <CPVvert_index_integer> \

<CPVvert_index_integer> <CPVvert_index_integer>

Sets the indexed c-p-v face topology from 3 c-p-v vertex index number arguments

The c-p-v vertex and face indexes are 1-based as with other mesh indexes in MAXScript. Remember that you need to call update() on the mesh after making changes to it for the changes to be reflected in the scene.

Notes

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 Working with Editable Meshes.

Subdivision Displacement Surface Properties Methods

The following methods set the Subdivision Displacement Surface Properties for a mesh object. These methods are not applicable to TriMeshes.

setSplitMesh <mesh> <boolean>

Turns on or off split mesh subdivision displacement for the mesh. Calling this function will enable subdivisionDisplacement if it is set to false.

getSplitMesh <mesh>

Returns true if split mesh subdivision displacement is turned on for the mesh, false otherwise.

setSubdivisionDisplacement <mesh> <boolean>

Turns on or off subdivision displacement for the mesh.

getSubdivisionDisplacement <mesh>

Returns true if subdivision displacement is turned on for the mesh, false if off.

displacementToPreset <mesh> ( #low | #medium | #high )

Sets the mesh subdivision parameters to the specified preset value set.

setDisplacementMapping <mesh> <boolean>

Turns on or off whether to perform displacement mapping for the mesh. There is no corresponding user interface element for this method.

getDisplacementMapping <mesh>

Returns true if displacement mapping is turned on for the mesh, false if off.

Editable Mesh Modify Panel Command Modes and Operations

A suite of methods provide the ability for a script to invoke Editable Mesh and Edit Mesh Modify panel modes and operations, corresponding to buttons available at various mesh sub-object levels. These methods reside in the meshOps global structure. These methods effectively "push the button" in the 3ds max Modify panel. In order to use these methods, the node must be selected and the Modify panel open. In the description of these methods, the first argument <editable_mesh_node_or_modifier> should be interpreted as either an Editable Mesh node where the modifier stack level is at the base object, or an Edit Mesh modifier where the modifier stack level is at the Edit Mesh. In all cases, the following methods work at the current sub-object level, but only if that level is appropriate for the invoked operation.

If you have made scripted changes to the mesh you must call the update() method on the mesh before calling these methods. You do not need to call update() after just calling one of these methods, as 3ds max will take care of updating the mesh.

The follow methods invoke one of the 'user-interaction' button operations in the Editable Mesh Modify panel, acting on the currently selected sub-objects. These methods highlight the corresponding button in the Edit Geometry rollout and start the operation, at which point the user interactively completes the operation. These methods return after starting the operation, and before the user completes the operation, so care should be taken to ensure that your script does not interfere with the operation. Invoking any of these methods is the same as clicking on the associated button in the Modify panel. Calling a method when the operation is already in effect (either due to a user action or a MAXScript command) causes the operation to be terminated and the highlight is removed from the button.

meshOps.startAttach <editable_mesh_node_or_modifier>

Enters "Attach" command mode - valid in Vertex, Face, Polygon, and Element Sub-Object levels, and when not in Sub-Object mode.

meshOps.startBevel <editable_mesh_node_or_modifier>

Enters "Bevel" command mode - valid in Edge, Face, Polygon, and Element Sub-Object levels.

meshOps.startChamfer <editable_mesh_node_or_modifier>

Enters "Chamfer" command mode - valid in Vertex and Edge Sub-Object levels.

meshOps.startCreate <editable_mesh_node_or_modifier>

Enters "Create" command mode, valid in Vertex, Face, Polygon, and Element Sub-Object levels.

meshOps.startCut <editable_mesh_node_or_modifier>

Enters "Cut" command mode - valid in Edge, Face, Polygon, and Element Sub-Object levels.

meshOps.startDivide <editable_mesh_node_or_modifier>

Divides selected edges into 2 edges, for selected face into 3 faces - valid in Edge, Face, Polygon, and Element Sub-Object levels.

meshOps.startExtrude <editable_mesh_node_or_modifier>

Enters "Extrude" command mode - valid in Face, Polygon, and Element Sub-Object levels.

meshOps.startFlipNormalMode <editable_mesh_node_or_modifier>

Enters "Flip Normal" command mode - valid in Face, Polygon, and Element Sub-Object levels.

meshOps.startSlicePlane <editable_mesh_node_or_modifier>

Enters "Slice Plane" command mode - valid in all Sub-Object levels, and when not in Sub-Object mode.

meshOps.startTurn <editable_mesh_node_or_modifier>

Enters "Turn " command mode - valid in Edge Sub-Object level.

meshOps.startWeldTarget <editable_mesh_node_or_modifier>

Enters "Weld Target " command mode - valid in Vertex Sub-Object level.

The following methods invoke one of the 'instantaneous' button operations in the Editable Mesh Modify panel, acting on the currently selected sub-objects:

meshOps.autoEdge <editable_mesh_node_or_modifier>

Automatically sets the edge visibility on the selected sub-objects - valid in Edge Sub-Object level.

meshOps.break <editable_mesh_node_or_modifier>

Creates a new vertex for each face attached to the selected sub-objects - valid in Vertex Sub-Object level.

meshOps.collapse <editable_mesh_node_or_modifier>

Collapses the selected sub-objects - valid in Vertex, Edge, Face, Polygon, and Element Sub-Object levels.

meshOps.createShapeFromEdges <editable_mesh_node_or_modifier>

Displays Create Shape dialog allowing the user to specify an object name, shape type, and whether to ignore hidden edges. Valid in Edge Sub-Object level.

meshOps.delete <editable_mesh_node_or_modifier>

Deletes the selected sub-objects - valid in Vertex, Face, Polygon, and Element Sub-Object levels.

meshOps.detach <editable_mesh_node_or_modifier>

Displays Detach dialog allowing the user to specify an object name or to detach as element, and whether to clone the selected subobjects. Valid in Vertex, Face, Polygon, and Element Sub-Object levels.

meshOps.explode <editable_mesh_node_or_modifier>

Displays Explode to Objects dialog allowing the user to specify an object name. Explodes the selected faces into multiple elements or objects based on the angles of its edges. Valid in Vertex, Face, Polygon, and Element Sub-Object levels.

meshOps.flipNormal <editable_mesh_node_or_modifier>

Flips the normal of the selected faces - valid in Face, Polygon, and Element Sub-Object levels.

meshOps.gridAlign <editable_mesh_node_or_modifier>

Aligns the selected sub-objects to the construction plane - valid in Vertex, Edge, Face, Polygon, and Element Sub-Object levels.

meshOps.hide <editable_mesh_node_or_modifier>

Hides the selected sub-objects - valid in Vertex, Face, Polygon, and Element Sub-Object levels.

meshOps.invisibleEdge <editable_mesh_node_or_modifier>

Sets selected edges invisible. Valid in Vertex Sub-Object level.

meshOps.makePlanar <editable_mesh_node_or_modifier>

Forces all selected sub-objects to become coplanar - valid in Vertex, Edge, Face, Polygon, and Element Sub-Object levels.

meshOps.removeIsolatedVerts <editable_mesh_node_or_modifier>

Deletes all isolated vertices in the object regardless of the current selection.

meshOps.selectOpenEdges <editable_mesh_node_or_modifier>

Selects all edges with only one face. Valid in Edge Sub-Object level.

meshOps.slice <editable_mesh_node_or_modifier>

Subdivides edges and faces based on Slice Plane. meshOps.startSlicePlane() must be called to enter the "Slice Plane" command mode before slice is valid. Valid in all Sub-Object levels, and when not in Sub-Object mode.

meshOps.tessellate <editable_mesh_node_or_modifier>

Tessellates the selected sub-objects - valid in Face, Polygon, and Element Sub-Object levels.

meshOps.unhideAll <editable_mesh_node_or_modifier>

Unhides the hidden sub-objects at the current Sub-Object level - valid in Vertex, Face, Polygon, and Element Sub-Object levels.

meshOps.unifyNormal <editable_mesh_node_or_modifier>

Unifies the normals of the selected faces - valid in Face, Polygon, and Element Sub-Object levels.

meshOps.viewAlign <editable_mesh_node_or_modifier>

Aligns all selected sub-objects to the 0,0,0 plane of the active viewport - valid in Vertex, Edge, Face, Polygon, and Element Sub-Object levels.

meshOps.visibleEdge <editable_mesh_node_or_modifier>

Sets selected edges visible. Valid in Edge Sub-Object level.

meshOps.weld <editable_mesh_node_or_modifier>

Welds the selected vertices - valid in Vertex Sub-Object level.

The meshOps methods depend on the Modify panel being open and the desired object, either an Editable Mesh base object or Edit Mesh modifier, being currently open in the panel. The meshOps methods do not perform any operation if these conditions aren't met. You will need to use MAXScript functions like max modify mode or setCommandPanelTaskMode mode:#modify to open the Modify panel, select <obj> to select the object, subObjectLevel = <n> to set the Sub-Object level, and modPanel.setCurrentObject <obj_or_modifier> to establish the right context for the new functions to operate. For example:

Example:

s=sphere() -- create a sphere

ConvertToMesh s -- convert to an Editable Mesh

s.selectedfaces=#{1..112} -- select half the faces

max modify mode -- open the Modify panel

select s -- select the sphere

modPanel.setCurrentObject s—set modifier stack to the base object

-- (not really needed in this example)

subObjectLevel = 4 -- set Sub-Object level to polygon

meshOps.startExtrude s -- start the face extrude command mode,

-- highlighting its button in the Edit

-- Geometry rollout, at which point the

-- user interactively performs the extrude.

Another example is:

meshOps.Hide (modPanel.getCurrentObject())

which would invoke the Hide button operation on the current object open in the Modify panel if it was an Edit Mesh modifier or Editable Mesh base object.


Working with Editable Meshes

Flipping Face Normals

The following function flips the face normal for all faces in the specified mesh object.

Example:

fn FlipObjNormal obj =

(

for f =1 to obj.numFaces do—for each face in the mesh

(

verts=getface obj f -- get its 3 vertices as a point3

local tmp=verts.x -- swap the first and third vertices

verts.x=verts.z -- which flips the normal

verts.z=tmp -- (right-hand rule), and

setface obj f verts -- store the new vertex order for the face

)

update obj -- update object so 3ds max sees the changes

)

Texture Vertices and Faces

The following script is an example of working with texture vertices and faces.

Script:

-- function to apply planar mapping to an object

-- direction parameter specifies the axis the mapping is

-- perpendicular to, and can have a value of #x, #y, or #z

--

fn ApplyPlanarMap obj direction =

( local oldcoordsys, normalize_pos

-- in this case, the number of texture vertices is equal to the

-- number of mesh vertices

obj.numtverts=obj.numverts

-- build the texture vertex faces

buildTVFaces obj

-- operate in objects coordinate space. Save original coord system so we

-- can restore later.

oldcoordsys=set coordsys local

-- for each vertex in mesh, get it's position and normalize the position

-- to a range of [0,0,0] to [1,1,1]. This is the planar UVW space.

for v = 1 to obj.numverts do

( normalize_pos=((getvert obj v)-obj.min)/(obj.max-obj.min)

-- flip around position component values based on which direction the

-- planar mapping is perpendicular to

case direction of

(#x:( tmp=normalize_pos.x

normalize_pos.x=normalize_pos.y

normalize_pos.y=normalize_pos.z

normalize_pos.z=tmp

)

#y:( tmp=normalize_pos.y

normalize_pos.y=normalize_pos.z

normalize_pos.z=tmp

)

)

-- set the corresponding texture vertex "position"

settvert obj v normalize_pos

)

-- done "positioning" the texture vertices. Build the texture faces.

-- since in this case there is a 1-to-1 correspondence between mesh and

-- texture vertices, the vertex indices for a mesh face are also the

-- texture vertex indices for the texture faces.

for f = 1 to obj.numfaces do

setTVFace obj f (getface obj f)

-- all done. reset the coordinate system

set coordsys oldcoordsys

-- update the mesh so 3ds max sees the changes

update obj

)

--

-- test bed. Create a sphere, apply a material, set the diffuse map

-- to a 2x3 tiled checker map, turn on viewport display of the

-- checker texture map, and call the ApplyPlanarMap function

--

g=geosphere()

convertToMesh g

g.material=standard()

g.material.maps[2]=checker()

g.material.maps[2].coordinates.u_tiling=2

g.material.maps[2].coordinates.v_tiling=3

showTextureMap g.material g.material.maps[2] true

ApplyPlanarMap g #x

Output:

ApplyPlanarMap() -- output of function declaration lines 5 to 45

$GeoSphere:GeoSphere02 @ [0.0,0.0,0.0] -- output line 51

$Editable_Mesh:GeoSphere02 @ [0.0,0.0,0.0] -- output line 52

Standard:Standard -- output line 53

Checker:Checker -- output line 54

2 -- output line 55

3 -- output line 56

OK -- output line 57

OK -- output line 58


SplineShape : Shape

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

Spline Shape Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Class and Object Inspector Functions

Scripting Vertex and Control Point Animation

Notes

  1. You must convert existing shapes to SplineShapes in order to operate on them with the these methods. Use the convertToSplineShape() function to do this.

  2. Only the updateShape() function updates the shape's internal caches and images in 3ds max viewports. This is because updates can be computationally expensive and you don't want them performed on every function call. However, you must make sure you do call the updateShape() function after a series of changes and before the shape is to be worked on in 3ds max or by other functions in MAXScript.

  3. The in and out vectors for Bezier control points are given as vector handle coordinates, not as true vectors as the names suggests.

  4. Coordinates are given in the MAXScript working coordinate system - this is important to note if you are familiar with the corresponding SDK spline functions which always work in object-local coordinates.

  5. If the updateShape() function is called on an object that is selected and currently open in the Modify panel, it will drop the current selection in order to avoid a potential crash in 3ds max, which at the moment, does not support scripted changes to an object open in the Modify panel.

  6. If you are creating or modifying a spline object, and have not yet run updateShape() on the spline, 3ds max will crash if you minimize and then maximize the 3ds max window. This is because an only partially created spline is created, and the internal 3ds max spline structure is left in an unstable state.

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 Boolean default: 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 Scripting Vertex and Control Point Animation. For example, if a circle object is collapsed to a SplineShape, and some of its vertices are animated, the properties for the vertices and tangents would be similar to:

$Circle01.Spline_1___InVec_1 Point3 value: [-75,33,0] -- animatable

$Circle01.Spline_1___Vertex_1 Point3 value: [-75,33,0] -- animatable

$Circle01.Spline_1___OutVec_1 Point3 value: [-50,0,0] -- animatable

$Circle01.Spline_1___InVec_2 Point3 value: [-20,-33,0] -- animatable

$Circle01.Spline_1___Vertex_2 Point3 value: [7,-66,0] -- animatable

$Circle01.Spline_1___OutVec_2 Point3 value: [32,-95,0] -- animatable

Methods

Shape Methods

updateShape <shape>

Updates the shape's internal caches and viewport display to account for all the changes made by other functions in this kit. This update must be done before 3ds max or any other code tries to work with a modified shape object.

The updateShape() function makes any scripted changes to a base object spline shape propagate into the bottom of any modifier stack that is present. Note that there is no check to warn you that modifications such as topology changes might invalidate modifiers already in the stack. This is equivalent to opening and modifying the base object in a Modify panel, ignoring its warnings about invalidating the object.

resetShape <shape>

Clears all the spline curves out of a shape

numSplines <shape>

Returns the number of spline curves in the shape as an integer. Equivalent to <shape>.numSplines.

setFirstSpline <shape> <spline_index_integer>

Rolls the order of the splines in a shape around so that the numbered spline is the first spline in the shape. This is useful when working with multi-spline shapes in the Lofter and some other modifiers such as Surface Tools which are sensitive to spline order.

hideselectedsplines <shape>

Hides the selected splines in the shape.

hideselectedsegments <shape>

Hides the selected segments in the shape.

hideselectedverts <shape>

Hides the segments attached to the selected knots in the shape.

unhidesegments <shape>

Unhides all segments in the shape.

addAndWeld <to_shape> <from_shape> <weldthreshold_float>

Add the splines from one spline shape to the specified bezier shape. The weld threshold will weld the endpoints of the new splines onto endpoints of existing ones if they are within the distance specified.

bindKnot <shape> <isEnd_boolean> <splineId_integer> \

<segIndex_integer> <splineSegId_integer>

Binds the first or end knot of a spline to the midpoint of the specified segment. A bind acts as a constraint, it constrains the first point or the end point of a spline to the mid point of a segment. If <isEnd_boolean> is true the end knot of the spline is bound, otherwise the first knot is bound. <splineId_integer> specifies the index of the spline the first/end knot to bind belongs to, <segIndex_integer> specifies the index of the segment to bind to, and <splineSegId_integer> specifies the index of the spline the bind to segment belongs to.

unBindKnot <shape> <spline_index_integer> <isEnd_boolean>

Unbinds the specified end/first knot of the given spline

updateBindList <shape>

Called when the topology changes to update the bind list, for example when knots are deleted from bound spline or the spline bound to.

materialID <shape> <spline_index_integer> <segment_index_integer>

Returns the material id for the given segment of the given shape object.

animateVertex <shape> <vertex_spec>

Applies controllers to the specified vertices and tangents of the splineshape, where <vertex_spec> is one of:

<integer_index>

<integer_index_array>

#all

By assigning controllers to the vertices and tangents, the vertices and tangents are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the vertices and tangents. For example,

animateVertex $Circle01 #all

The vertices to be animated are specified by index number or with the keyword #all to animate all vertices.

See also Class and Object Inspector Functions and Scripting Vertex and Control Point Animation for details on accessing the splineshape vertices and tangents. The controller values assigned to the vertices and tangent handles is in object space. See Using Node Transform Properties for information on converting between world space to object space.

Spline Methods

addNewSpline <shape>

Adds a new spline curve to the spline shape and returns an integer reflecting the spline index of the newly added spline curve. Individual spline curves are given index numbers starting at 1. The addNewSpline() function adds new spline curves to the end of the list of curves in a shape.

getSplineSelection <shape>

Returns the indices of the selected splines in the shape as an array of integers.

setSplineSelection <shape> <spline_index_array> [ keep:<boolean> ]

Selects the splines specified by <spline_index_array> in the specified shape. <spline_index_array> is an array of integers specifying the spline indices. Splines already selected are de-selected unless keep:true is specified.

deleteSpline <shape> <spline_index_integer>

Deletes the indexed spline curve from the shape. The remaining curves are renumbered to account for the deletion.

numSegments <shape> <spline_index_integer>

Returns the number of line segments in the indexed spline as an integer. This is the same as the number of knots for closed splines and 1 less for open splines.

numKnots <shape> [ <spline_index_integer> ]

Returns the number of knots (also known vertices or control points) in the indexed spline as an integer. If the spline index is not specified, returns the number of knots in the entire shape.

isClosed <shape> <spline_index_integer>

returns true if the indexed spline is closed, false if it is open.

close <shape> <spline_index_integer>

closes the indexed spline.

open <shape> <spline_index_integer>

opens the indexed spline between its last and first knots.

reverse <shape> <spline_index_integer>

reverses the order of the knots in the indexed spline.

setFirstKnot <shape> <spline_index_integer> <knot_index_integer>

rolls the order of the knots in the indexed spline around so that the specified knot becomes the first knot in the spline.

getSegLengths <splineShape> <spline_index> [cum:<boolean>] [byVertex:<boolean>] [numArcSteps:<integer>]

Returns array of segment lengths or vertex distances by spline fraction and length, and total spline length. Double precision calculations, very accurate. If cum:true, results are cumulative, otherwise they are relative. If byVertex:true results are per vertex, otherwise per segment.

Defaults: cum:false byVertex:false numArcSteps:100

subdivideSegment <splineShape> <spline_index> <seg_index> <divisions>

Divides the segment into the specified number of divisions. Double precision calculations, very accurate.

interpCurve3D <splineShape> <spline_index> <param_float> [pathParam:<boolean>]

Returns a <point3> coordinate on the indexed curve. If pathParam:false, param is the fraction of the spline length, otherwise it is a segment-based (path) fraction. Default is pathParam:false

tangentCurve3D <splineShape> <spline_index> <param_float> [pathParam:<boolean>]

Returns a <point3> tangent on the indexed curve. If pathParam:false, param is the fraction of the spline length, otherwise it is a segment-based (path) fraction. Default is pathParam:false

Segment Methods

getSegmentType <shape> <spline_index_integer> <seg_index_integer>

Gets the segment type of the indexed segment in the indexed spline

setSegmentType <shape> <spline_index_integer> \

<seg_index_integer> ( #curve | #line )

Sets the segment type of the indexed segment in the indexed spline

refineSegment <shape> <spline_index_integer> \

<seg_index_integer> <seg_interp_param_float>

Adds a new knot to the indexed segment of the indexed curve at a place along the indexed segment corresponding to the given segment interpolation parameter. This value is a float in the range 0.0 to 1.0, specifying a proportion along the segment. The new knot coordinates and in-vector and out-vector are automatically computed to maintain the segment's existing curvature. This is the primitive used by the refine function in the Edit Spline modifier. You can use the MAXScript spline path interpolation functions to derive segment parameters given that a curve's path interpolation parameter is divided evenly among the segments in a curve. (So given a path interpolation parameter u and a target segment n in a spline of m segments, the segment parameter is u - (n-1)/m.) The refineSegment() function returns the index of the newly inserted knot.

getSegSelection <shape> <spline_index_integer>

Returns the indices of the selected segments in the specified shape spline as an array of integers.

setSegSelection <shape> <spline_index_integer> \

<segment_index_array> [ keep: <boolean> ]

Selects the segments specified by <segment_index_array> in the specified shape spline. <segment_index_array> is an array of integers specifying the segment indices. Segments already selected are de-selected unless keep:true is specified.

setMaterialID <splineShape> <spline_index> <seg_index> <matID>

Sets the material ID of the specified spline segment.

getMaterialID <splineShape> <spline_index> <seg_index>

Gets the material ID of the specified spline segment.

Knot Methods

addKnot <shape> <spline_index_integer> \

( #smooth | #corner | #bezier | #bezierCorner ) \

( #curve | #line ) <position_point3> \

[invec_point3 outvec_point3] [where_integer]

Adds a new knot (control point) to the indexed spline and returns an integer reflecting the index of the newly added knot. The 3rd argument specifies the type of the knot, the 4th specifies the type of the segment leaving the knot. The 5th specifies the coordinates for the new point (given in the current working coordinate system). If the knot type is bezier or bezierCorner, you must give the in-vector and out-vector handle coordinates as the 6th and 7th arguments. In the same way as splines are indexed in a shape, knots are indexed in a spline. The optional last argument lets you specify where in the knot order the new knot is to be inserted, defaulting to the end of the spline if you leave this argument off.

deleteKnot <shape> <spline_index_integer> <knot_index_integer>

Deletes the indexed knot in the indexed spline. The remaining knots are renumbered to account for the deletion.

getKnotType <shape> <spline_index_integer> <knot_index_integer>

Returns the knot type of the indexed knot in the indexed spline. The value is one of the names #smooth, #corner, #bezier, or #bezierCorner.

setKnotType <shape> <spline_index_integer> <knot_index_integer> \

(#smooth | #corner | #bezier | #bezierCorner )

Sets the knot type of the indexed knot in the indexed spline. This is equivalent to the right-mouse-button change you can make to spline control-points using the Edit Spline modifier in 3ds max.

getKnotPoint <shape> <spline_index_integer> <knot_index_integer>

Retrieves the coordinates of the indexed knot as a point3 in the current working coordinate system.

setKnotPoint <shape> <spline_index_integer> <knot_index_integer> <point3>

Sets the coordinates of the indexed knot in the indexed spline. Coordinates are given in the current working coordinate system.

getInVec <shape> <spline_index_integer> <knot_index_integer>

Retrieves the coordinates of the in-vector handle for the indexed knot as a point3 in the current working coordinate system.

setInVec <shape> <spline_index_integer> <knot_index_integer> <point3>

Sets the coordinates of the in-vector handle of the indexed knot. Coordinates are given in the current working coordinate system.

getOutVec <shape> <spline_index_integer> <knot_index_integer>

Retrieves the coordinates of the out-vector handle for the indexed knot as a point3 in the current working coordinate system.

setOutVec <shape> <spline_index_integer> <knot_index_integer> <point3>

Sets the coordinates of the out-vector handle of the indexed knot. Coordinates are given in the current working coordinate system.

getKnotSelection <shape> <spline_index_integer>

Returns the indices of the selected knots in the specified shape spline as an array of integers.

setKnotSelection <shape> <spline_index_integer> \

<knot_index_array> [keep: <boolean> ]

Selects the knots specified by <knot_index_array> in the specified shape spline. <knot_index_array> is an array of integers specifying the knot indices. Knots already selected are de-selected unless keep:true is specified.

Editable Spline Modify Panel Command Modes and Operations

A suite of methods provide the ability for a script to invoke Editable Spline, Line, and Edit Spline Modify panel modes and operations, corresponding to buttons available at various shape sub-object levels. These methods reside in the splineOps global structure. These methods effectively "push the button" in the Modify panel. In order to use these methods, the node must be selected and the Modify panel open. In the description of these methods, the first argument <editable_spline_or_line_node_or_modifier> should be interpreted as either an Editable Spline or Line node where the modifier stack level is at the base object, or an Edit Spline modifier where the modifier stack level is at the Edit Spline. In all cases, the following methods work at the current sub-object level, but only if that level is appropriate for the invoked operation.

If you have made scripted changes to the shape you must call the updateShape() method on the mesh before calling these methods. You do not need to call updateShape() after just calling one of these methods, as 3ds max will take care of updating the shape.

The following methods invoke one of the 'user-interaction' button operations in the Editable Spline Modify panel, acting on the currently selected sub-objects. These methods highlight the corresponding button in the Geometry rollout and start the operation, at which point the user interactively completes the operation. These methods return after starting the operation, and before the user completes the operation, so care should be taken to ensure that your script does not interfere with the operation. Invoking any of these methods is the same as clicking on the associated button in the Modify panel. Calling a method when the operation is already in effect (either due to a user action or a MAXScript command) causes the operation to be terminated and the highlight is removed from the button.

splineOps.startUnion <editable_spline_or_line_node_or_modifier>

Enters "Boolean Union" command mode - valid in Spline Sub-Object level. Only 1 closed spline must be selected to enter this command mode.

splineOps.startSubtract <editable_spline_or_line_node_or_modifier>

Enters "Boolean Subtract" command mode - valid in Spline Sub-Object level. Only 1 closed spline must be selected to enter this command mode.

splineOps.intersect <editable_spline_or_line_node_or_modifier>

Enters "Boolean Intersect" command mode - valid in Spline Sub-Object level. Only 1 closed spline must be selected to enter this command mode.

splineOps.startAttach <editable_spline_or_line_node_or_modifier>

Enters "Attach" command mode - valid in all Sub-Object levels, and when not in Sub-Object mode.

splineOps.startBind <editable_spline_or_line_node_or_modifier>

Enters "Bind" command mode - valid in Vertex Sub-Object level.

splineOps.startBreak <editable_spline_or_line_node_or_modifier>

Enters "Break" command mode - valid in Vertex and Segment Sub-Object levels.

splineOps.startChamfer <editable_spline_or_line_node_or_modifier>

Enters "Chamfer" command mode - valid in Vertex Sub-Object level.

splineOps.startConnect <editable_spline_or_line_node_or_modifier>

Enters "Connect" command mode - valid in Vertex Sub-Object level.

splineOps.startCreateLine <editable_spline_or_line_node_or_modifier>

Enters "Create Line" command mode - valid in all Sub-Object levels, and when not in Sub-Object mode.

splineOps.startCrossInsert <editable_spline_or_line_node_or_modifier>

Enters "CrossInsert" command mode - valid in Vertex Sub-Object level.

splineOps.startExtend <editable_spline_or_line_node_or_modifier>

Enters "Extend" command mode - valid in Spline Sub-Object level.

splineOps.startFillet <editable_spline_or_line_node_or_modifier>

Enters "Fillet" command mode - valid in Vertex Sub-Object level.

splineOps.startInsert <editable_spline_or_line_node_or_modifier>

Enters "Insert" command mode - valid in all Sub-Object levels, and when not in Sub-Object mode.

splineOps.startOutline <editable_spline_or_line_node_or_modifier>

Enters "Outline" command mode - valid in Spline Sub-Object level.

splineOps.startRefine <editable_spline_or_line_node_or_modifier>

Enters "Refine" command mode - valid in Vertex and Segment Sub-Object levels. This method does not turn off the Connect checkbox, so it is effectively the same as the startRefineConnect() method.

splineOps.startRefineConnect <editable_spline_or_line_node_or_modifier>

Enters "Refine" command mode - valid in Vertex and Segment Sub-Object levels. This method does not turn on the Connect checkbox, so it is effectively the same as the startRefine() method.

splineOps.startTrim <editable_spline_or_line_node_or_modifier>

Enters "Trim" command mode - valid in Spline Sub-Object level.

The following methods invoke one of the 'instantaneous' button operations in the Editable Shape Modify panel, acting on the currently selected sub-objects:

splineOps.attachMultiple <editable_spline_or_line_node_or_modifier>

Displays Attach Multiple dialog allowing the user to select multiple shapes to attach. Valid in all Sub-Object levels, and when not in Sub-Object mode.

splineOps.close <editable_spline_or_line_node_or_modifier>

Closes the selected splines – valid in Spline Sub-Object level.

splineOps.cycle <editable_spline_or_line_node_or_modifier>

Cycles through the vertices of the spline, selecting each vertex. At least one vertex must be selected before calling this method, or no vertex is selected. If more than one vertex is selected when this method is called, the first vertex of the first shape is selected. Valid in Vertex Sub-Object level.

splineOps.delete <editable_spline_or_line_node_or_modifier>

Deletes the selected sub-objects - valid in all Sub-Object levels.

splineOps.detach <editable_spline_or_line_node_or_modifier>

Displays Detach dialog allowing the user to specify an object name. Valid in all Sub-Object levels.

splineOps.divide <editable_spline_or_line_node_or_modifier>

Divides the selected segments - valid in Segment Sub-Object level.

splineOps.explode <editable_spline_or_line_node_or_modifier>

Explodes the each segment in the selected splines into separate splines or objects. Valid in Spline Sub-Object level.

splineOps.hide <editable_spline_or_line_node_or_modifier>

Hides the selected sub-objects - valid in all Sub-Object levels.

splineOps.makeFirst <editable_spline_or_line_node_or_modifier>

Makes the selected vertices the first vertex in the spline- valid in Vertex Sub-Object level.

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

Quadpatch ...

Tripatch ...

To create a Patch scene object from scratch, you call the Patch constructor function, for example:

Quadpatch pos:[10,10,10] name:"foo"

This creates an empty patch.

convertTo <node> Editable_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.

Properties

A control vertex and its tangents are available as properties once a controller has been assigned to the control vertex. The number of tangents for a control vertex is the number of edges associated with the control vertex. Controllers can not be assigned to the control vertices using MAXScript in 3ds max 4. If a TriPatch object is collapsed to a SplineShape, and some of its control vertices are animated, the properties for the control vertices and tangents would be similar to:

$TriPatch01.Vertex_1 Point3 value: [-21.5,-6.4,0] -- animatable

$TriPatch01.Vertex_1_Vector_1 Point3 value: [-21.5,-2.1,0] -- animatable

$TriPatch01.Vertex_1_Vector_2 Point3 value: [-7.1,-6.4,0] -- animatable

$TriPatch01.Vertex_2 Point3 value: [21.5,-6.4,0] -- animatable

$TriPatch01.Vertex_2_Vector_1 Point3 value: [7.1,-6.4,0] -- animatable

$TriPatch01.Vertex_2_Vector_2 Point3 value: [7.1,-2.1,0] -- animatable

See also Class and Object Inspector Functions for details on accessing the patch vertices and tangents. The controller values assigned to the vertices and tangent handles is in object space. See Using Node Transform Properties for information on converting between world space to object space.

Methods

getPatchSteps <editable_patch_node>

Returns the number of steps the patch uses in the viewports, and reflects the View Steps spinner in the Modify panel.

setPatchSteps <editable_patch_node> <integer>

Sets the number of View Steps used by the editable patch object to the specified value.

Editable Patch Modify Panel Command Modes and Operations

A suite of methods provide the ability for a script to invoke Editable Patch and Edit Mesh Modify panel modes and operations, corresponding to buttons available at various mesh sub-object levels. These methods reside in the patchOps global structure. These methods effectively "push the button" in the Modify panel. In order to use these methods, the node must be selected and the Modify panel open. In the description of these methods, the first argument <editable_patch_node_or_modifier> should be interpreted as either an Editable Patch node where the modifier stack level is at the base object, or an Edit Patch modifier where the modifier stack level is at the Edit Patch. In all cases, the following methods work at the current sub-object level, but only if that level is appropriate for the invoked operation.

The follow methods invoke one of the 'user-interaction' button operations in the Editable Patch Modify panel, acting on the currently selected sub-objects. These methods highlight the corresponding button in the Geometry rollout and start the operation, at which point the user interactively completes the operation. These methods return after starting the operation, and before the user completes the operation, so care should be taken to ensure that your script does not interfere with the operation. Invoking any of these methods is the same as clicking on the associated button in the Modify panel. Calling a method when the operation is already in effect (either due to a user action or a MAXScript command) causes the operation to be terminated and the highlight is removed from the button.

patchOps.startAttach <editable_patch_node_or_modifier>

Enters "Attach" command mode - valid in all Sub-Object levels, and when not in Sub-Object mode.

patchOps.startBevel <editable_patch_node_or_modifier>

Enters "Bevel" command mode - valid in Patch Sub-Object level.

patchOps.startBind <editable_patch_node_or_modifier>

Enters "Bind" command mode - valid in Vertex Sub-Object level.

patchOps.startCreate <editable_patch_node_or_modifier>

Enters "Create" command mode - valid in Vertex, Patch, and Element Sub-Object levels.

patchOps.startExtrude <editable_patch_node_or_modifier>

Enters "Extrude" command mode - valid in Patch Sub-Object level.

patchOps.startFlipNormalMode <editable_patch_node_or_modifier>

Enters "Flip Normal" command mode - valid in Patch and Element Sub-Object levels.

patchOps.startWeldTarget <editable_patch_node_or_modifier>

Enters "Weld Target" command mode - valid in Vertex Sub-Object level.

The following methods invoke one of the 'instantaneous' button operations in the Editable Patch Modify panel, acting on the currently selected sub-objects:

patchOps.addTri <editable_patch_node_or_modifier>

Adds a TriPatch to the selected edge - valid in Edge Sub-Object level.

patchOps.addQuad <editable_patch_node_or_modifier>

Adds a QuadPatch to the selected edge - valid in Edge Sub-Object level.

patchOps.break <editable_patch_node_or_modifier>

Creates a new vertex for each patch attached to the selected sub-objects - valid in Vertex and Edge Sub-Object levels.

patchOps.clearAllSG <editable_patch_node_or_modifier>

Clears the smoothing groups on the currently selected patches - valid in Face, Polygon, and Element Sub-Object levels.

patchOps.createShapeFromEdges <editable_patch_node_or_modifier>

Displays Create Shape dialog allowing the user to specify an object name for the shape to create from the selected edges. Valid in Edge Sub-Object level.

patchOps.delete <editable_patch_node_or_modifier>

Deletes the selected sub-objects - valid in all Sub-Object levels.

patchOps.detach <editable_patch_node_or_modifier>

Displays Detach dialog allowing the user to specify an object name. Valid in Patch Sub-Object level.

patchOps.flipNormal <editable_patch_node_or_modifier>

Flips the normal of the selected patches - valid in Patch and Element Sub-Object levels.

patchOps.hide <editable_patch_node_or_modifier>

Hides the selected sub-objects - valid in all Sub-Object levels.

patchOps.selectByID <editable_patch_node_or_modifier>

Display a Select By Material ID dialog and choose patches with the specified material ID - valid in Patch and Element Sub-Object levels.

patchOps.selectBySG <editable_patch_node_or_modifier>

Display a Select By Smooth Groups dialog and choose patches with the specified smoothing groupd IDs - valid in Patch and Element Sub-Object levels.

patchOps.selectOpenEdges <editable_patch_node_or_modifier>

Selects all edges with only one patch. Valid in Edge Sub-Object level.

patchOps.subdivide <editable_patch_node_or_modifier>

Divides the selected sub-objects - valid in Edge and Patch Sub-Object levels.

patchOps.unbind <editable_patch_node_or_modifier>

Unbinds the selected vertices - valid in Vertex Sub-Object level.

patchOps.unifyNormal <editable_patch_node_or_modifier>

Unifies the normals of the selected patches - valid in Patch and Element Sub-Object levels.

patchOps.unhideAll <editable_patch_node_or_modifier>

Unhides all hidden sub-objects -valid in all Sub-Object levels, and when not in Sub-Object mode.

patchOps.weld <editable_patch_node_or_modifier>

Welds the selected vertices - valid in Vertex Sub-Object level.

There is now a new patch function containing a large number of functions for creating, modifying and accessing patch objects.

The following functions are used to get and set the overall geometry of the patch.

Set keep:true to the setNumXXX functions for them to retain existing vertex/vector/patch/edge data. This value defaults to false, which cleans out the geometry

patch.getNumVerts <obj> -> integer

patch.setNumVerts <obj> <num> [keep:<boolean>]

patch.getNumVecs <obj> -> integer

patch.setNumVecs <obj> <num> [keep:<boolean>]

patch.getNumPatches <obj> -> integer

patch.setNumPatches <obj> <num> [keep:<boolean>]

patch.getNumEdges <obj> -> integer

patch.setNumEdges <obj> <num> [keep:<boolean>]

The following functions get and set individual vertex and vector handle locations. The vertex and vector coordinates are interpreted in MAXScript's current working coordinate context. Consistent with the rest of MAXScript, all vertex/patch/vector/edge indexes start numbering at 1.

patch.getVert <obj> <index> -> Point3

patch.setVert <obj> <index> <point3>

patch.getVec <obj> <index> -> Point3

patch.setVec <obj> <index> <point3>

The following two functions are the main mechanism for creating individual patches in the patch mesh.

patch.makeQuadPatch <obj> <index> <va> <vab> <vba> <vb> <vbc> <vcb> <vc> <vcd> <vdc> <vd> <vda> <vad> <i1> <i2> <i3> <i4> <sm>

where:

index = The index of the patch to create (0> = index < numPatches).

va = The first vertex.

vab = Vector ab.

vba = Vector ba.

vb = The second vertex.

vbc = Vector bc.

vcb = Vector cb.

vc = The third vertex.

vcd = Vector cd.

vdc = Vector dc.

vd = The fourth vertex.

vda = Vector da.

vad = Vector ad.

i1 = Interior 1.

i2 = Interior 2.

i3 = Interior 3.

i4 = Interior 4.

sm = The smoothing group mask

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

where:

index = The index of the patch to create (0> = index < numPatches).

va = The first vertex.

vab = Vector ab.

vba = Vector ba.

vb = The second vertex.

vbc = Vector bc.

vcb = Vector cb.

vc = The third vertex.

vca = Vector ca.

vac = Vector ac.

i1 = Interior 1.

i2 = Interior 2.

i3 = Interior 3.

sm = The smoothing group mask

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

patch.update <obj>

The following functions give access to the topology of an existing patch object. They return either indexes or arrays of indexes of the sub-objects requested. For example, getVertVecs() returns an array of the vectors coming out of the specified vertex.

patch.getVertVecs <obj> <index> -> integer_array

patch.getVertPatches <obj> <index> -> integer_array

patch.getVertEdges <obj> <index> -> integer_array

patch.getVecVert <obj> <index> -> integer

patch.getVecPatches <obj> <index> -> integer_array

patch.getEdgeVert1 <obj> <index> -> integer

patch.getEdgeVert2 <obj> <index> -> integer

patch.getEdgeVec12 <obj> <index> -> integer

patch.getEdgeVec21 <obj> <index> -> integer

The following functions access and manipulate the texture mapping information in the patch object.

patch.setNumMaps <obj> <num> [keep:<bool>] ->

patch.getNumMaps <obj> -> integer

patch.setMapSupport <obj> <map_chan> [init:<boolean>] ->

patch.getMapSupport <obj> <map_chan> -> boolean

patch.maxMapChannels <obj> ->

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

patch.getNumMapVerts <obj> <map_index>

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

patch.getMapVert <obj> <map_chan> <index>

patch.setMapVert <obj> <map_chan> <index> <point3>

patch.getMapPatch <obj> <map_chan> <index>

patch.setMapPatch <obj> <map_chan> <index> <index_array>

The following functions get and set the material ID for the patch object as a whole or for individual patches.

patch.getMtlID <obj> -> integer

patch.setMtlID <obj> <mtl_id>

patch.getPatchMtlID <obj> <index> -> integer

patch.setPatchMtlID <obj> <patch_index> <mtl_id>

The following functions access and control viewport and renderer tesselation and visibility.

patch.setMeshSteps <obj> <steps>

patch.getMeshSteps <obj>

patch.setMeshStepsRender <obj> <steps>

patch.getMeshStepsRender <obj>

patch.setShowInterior <obj> <bool>

patch.getShowInterior <obj>

patch.setAdaptive <obj> <bool>

patch.getAdaptive <obj>

The following functions access topology info for the specified sub-object.

patch.getEdges <obj> <v1> [<v2>] -> integer_array

patch.getPatches <obj> <v1> [<v2>] -> integer_array

patch.getVectors <obj> <vert> -> integer_array

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

patch.transform <obj> <matrix3>

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

patch.weldVerts <obj> <threshold> <weldIdentical_bool> <startVert>

patch.weld2Verts <obj> <v1> <v2>

patch.weldEdges <obj>

patch.deletePatchParts <obj> <del_vert_bitarray> <del_patches_bitarray>

patch.clonePatchParts <obj> <patch_bit_array>

patch.subdivideEdges <obj> <propogate>

patch.subdividePatches <obj> <propogate>

patch.addTriPatch <obj>

patch.addQuadPatch <obj>

The following functions get and manipulate surface normal information. Again, normal vectors are given in MAXScript's current working coordinate context.

patch.patchNormal <obj> <patch>

patch.edgeNormal <obj> <edge>

patch.updatePatchNormals <obj>

patch.flipPatchNormal <obj> <patch>

patch.unifyNormals <obj>

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

The following functions access and change the vertex and interior vertex types:

patch.changeVertType <obj> <vert> #corner|#coplanar

patch.getVertType <obj> <vert> -> #corner or #coplanar

patch.changePatchInteriorType <obj> <patch> #automatic|#manual

patch.getPatchInteriorType <obj> <patch> -> #automatic or #manual

The following function returns the current mesh tesselation for the patch object:

patch.getMesh <obj> -> mesh value

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

patch.interpTriPatch <obj> <patch> <u> <v> <w> -> point3

patch.interpQuadPatch <obj> <patch> <u> <v> -> point3

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Class and Object Inspector Functions

Scripting Vertex and Control Point Animation


Editable_Poly: GeometryClass

Editable_Poly is the general editable version of all the editable poly objects, in the same way that Editable meshes relate to geometry objects. They are the class of node objects that are the result of collapsing a modifier stack to an editable mesh object.

Constructor

Properties

Methods

Editable Poly Modify Panel Command Modes and Operations

A suite of methods provide the ability for a script to invoke Editable Poly Modify panel modes and operations, corresponding to buttons available at various sub-object levels. These methods reside in the polyOp and polyOps global structures. 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_poly_node_or_modifier> should be interpreted as either an Editable Poly node where the modifier stack level is at the base object, or an Edit Poly modifier where the modifier stack level is at the Edit Poly. 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 Poly 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.

Many of the polyOp methods take as an argument <vertlist>, <facelist>, or <edgelist>. These arguments specify the sub object (SO) elements to operate on. These arguments can be specified as:

#all - all SO elements of that type

#selection - the current SO selection of that type

#none - none of the SO elements of that type

An array of integers, where each integer value specifies a SO element index

A bitarray, where each bit specifies a SO element index

A value convertable to an integer that specifies a SO element index

A VertexSelection, EdgeSelection, or FaceSelection value. The value type must match the specified SO type.

All polyOp methods take as an argument <poly>, the poly to operate on. This argument can be either a node value where the base object of the node is an Editable Poly, or the Editable Poly base object.

Editable polys can have "dead" vertices, edges, and faces. These are SO elements that have been deleted from the poly, but have not yet been removed from the corresponding lists of SO elements. SO elements may be marked as dead in the process of performing certain operations on the poly, but the SO element lists are normally collapsed (that is, all dead SO elements removed) at the end of the operation. Thus, normally there should not be any dead SO elements present in the poly. If you flag a SO element as dead using one of the polyOp methods, you should also call collapseDeadStructs to collapse the SO element lists.

Other than methods that get/set SO element flags, dead SO elements are normally ignored by the polyOp methods. If a method returns a value other than OK, takes a single SO element index, and that SO element is dead, a value of UNDEFINED is normally returned.

polyOp.getVertSelection <Poly poly>

Returns the current vertex selection as a bitarray

polyOp.setVertSelection <Poly poly> <vertlist>

Sets the current vertex selection based on <vertlist>

polyOp.getEdgeSelection <Poly poly>

Returns the current edge selection as a bitarray

polyOp.setEdgeSelection <Poly poly> <edgelist>

Sets the current edge selection based on <vertlist>

polyOp.getFaceSelection <Poly poly>

Returns the current face selection as a bitarray

polyOp.setFaceSelection <Poly poly> <facelist>

Sets the current face selection based on <facelist>

polyOp.getDeadVerts <Poly poly>

Returns the current dead vertices selection as a bitarray. Normally this will return an empty bitarray.

polyOp.getDeadEdges <Poly poly>

Returns the current dead edges selection as a bitarray. Normally this will return an empty bitarray.

polyOp.getDeadFaces <Poly poly>

Returns the current dead faces selection as a bitarray. Normally this will return an empty bitarray.

polyOp.getVertsByFlag <Poly poly> <int flag> mask:<int maskflag>

Each vertex in a poly contains a 32 bit flag variable. This method returns a bitarray of the vertices that have all the bits specified in <flag> also set in the flag variable. If mask: is specified, any vertices where any of the bits specified in the <maskflag> are also set in the flag variable are not included in the resulting bitarray. If bit 2 of <flag> is not set, signifying the vertex is dead, dead vertices are not included in the resulting bitarray. The vertex level flags are:

bit 1: vertex is selected

bit 2: vertex is dead

bit 3: reserved

bit 4: indicates the vertex faces "backwards" in the current viewport

bit 5-24: reserved

bit 25-32: available for general use

polyOp.getVertFlags <Poly poly> <int vert>

Returns the flags bits for the vertex as an integer.

polyOp.setVertFlags <Poly poly> <vertlist> <int flag> mask:<int=0> undoable:<boolean=false>

Sets the flag bits on the specified vertices to the bits in <flag>. If mask is specified, the bits set in the mask value are cleared for all vertices in the poly prior to setting flag bits on the specified vertices. If undoable:true is specified, this operation is undoable. If bits 1 or 2 of <flag> are set (selected and dead flag bits), this operation is always undoable.

Example:

p=convertToPoly (plane())

p.selectedVerts = #{10..20}

i=1 -- selected bit

j=bit.set 0 30 true -- bit 30 set

oldflags = for k = 1 to p.numverts collect polyop.getVertFlags p k

theSet=#{5..15}

polyop.setvertflags p theSet j mask:i

for k = 1 to p.numverts do

(

nf=polyop.getVertFlags p k

format "% : % : %\n" k nf oldflags[k]

oldflags[k]=nf

)

j=bit.set 0 1 true -- bit 1 set

polyop.setvertflags p theSet j

for k = 1 to p.numverts do

(

nf=polyop.getVertFlags p k

format "% : % : %\n" k nf oldflags[k]

)

polyOp.getEdgesByFlag <Poly poly> <int flag> mask:<int maskflag>

Each edge in a poly contains a 32 bit flag variable. This method returns a bitarray of the edges that have all the bits specified in <flag> also set in the flag variable. If mask: is specified, any edges where any of the bits specified in the <maskflag> are also set in the flag variable are not included in the resulting bitarray. If bit 2 of <flag> is not set, signifying the edge is dead, dead edges are not included in the resulting bitarray. The edge level flags are:

bit 1: edge is selected

bit 2: edge is dead

bit 3: reserved

bit 4: indicates the vertex faces "backwards" in the current viewport

bit 5-24: reserved

bit 25-32: available for general use

polyOp.getEdgeFlags <Poly poly> <int edge>

Returns the flags bits for the edge as an integer.

polyOp.setEdgeFlags <Poly poly> <edgelist> <int flag> mask:<int=0> undoable:<boolean=false>

Sets the flag bits on the specified edges to the bits in <flag>. If mask is specified, the bits set in the mask value are cleared for all edges in the poly prior to setting flag bits on the specified edges. If undoable:true is specified, this operation is undoable. If bits 1 or 2 of <flag> are set (selected and dead flag bits), this operation is always undoable.

polyOp.getFacesByFlag <Poly poly> <int flag> mask:<int maskflag>

Each face in a poly contains a 32 bit flag variable. This method returns a bitarray of the faces that have all the bits specified in <flag> also set in the flag variable. If mask: is specified, any faces where any of the bits specified in the <maskflag> are also set in the flag variable are not included in the resulting bitarray. If bit 2 of <flag> is not set, signifying the face is dead, dead faces are not included in the resulting bitarray. The face level flags are:

bit 1: face is selected

bit 2: face is dead

bit 3: reserved

bit 4: indicates the vertex faces "backwards" in the current viewport

bit 5-24: reserved

bit 25-32: available for general use

polyOp.getFaceFlags <Poly poly> <int face>

Returns the flags bits for the face as an integer.

polyOp.setFaceFlags <Poly poly> <facelist> <int flag> mask:<int=0> undoable:<boolean=false>

Sets the flag bits on the specified faces to the bits in <flag>. If mask is specified, the bits set in the mask value are cleared for all faces in the poly prior to setting flag bits on the specified faces. If undoable:true is specified, this operation is undoable. If bits 1 or 2 of <flag> are set (selected and dead flag bits), this operation is always undoable.

polyOp.getNumVerts <Poly poly>

Returns the number of vertices in the poly. Includes any dead vertices.

polyOp.getNumEdges <Poly poly>

Returns the number of edges in the poly. Includes any dead edges.

polyOp.getNumFaces <Poly poly>

Returns the number of faces in the poly. Includes any dead faces.

polyOp.GetHasDeadStructs <Poly poly

Bit 1 in the return value is set if the poly has any dead vertices, bit 2 if any dead edges, and bit 3 if any dead faces.

polyOp.getHiddenVerts <Poly poly>

Bits in the result bitarray are set if the corresponding vertex is hidden.

polyOp.setHiddenVerts <Poly poly> <vertlist>

Hides the corresponding vertices in the poly

polyOp.getHiddenFaces <Poly poly>

Bits in the result bitarray are set if the corresponding face is hidden.

polyOp.setHiddenFaces <Poly poly> <facelist>

Hides the corresponding faces in the poly

polyOp.unHideAllFaces <Poly poly>

Unhides all faces in the poly.

polyOp.unHideAllVerts <Poly poly>

Unhides all vertices in the poly.

polyOp.getEdgeVis <Poly poly> <int edge>

Returns true if the specified edge is visible, false otherwise.

polyOp.setEdgeVis <Poly poly> <edgelist> <boolean>

Sets the visibility of the specified edges.

polyOp.getOpenEdges <Poly poly>

Bits in the result bitarray are set if the corresponding edge is open (used by only 1 ace).

polyOp.getBorderFromEdge <Poly poly> <int edge>

Bits in the result bitarray are set for open edges in the poly that are connected via open edges to the specified edge.

All one-sided edges in polys can be grouped into chains, end to end, that represent boundaries of the poly. For instance, in a box with one side deleted, all the one-sided edges are part of the chain that goes around the hole. If the specified edge isn't open, the resulting bitarray is empty.

polyOp.getFaceVerts <Poly poly> <int face>

Returns the face's vertices as an array. The order of the vertices in the array corresponds to the order of the vertices in the face.

polyOp.getFaceEdges <Poly poly> <int face>

Returns the face's edges as an array. The order of the edges in the array corresponds to the order of the edges in the face.

polyOp.getEdgeVerts <Poly poly> <int edge>

Returns the edge's vertices as a 2 element array.

polyOp.isFaceDead <Poly poly> <int face>

Returns true if the specified face is dead.

polyOp.isEdgeDead <Poly poly> <int edge>

Returns true if the specified edge is dead.

polyOp.isVertDead <Poly poly> <int vert>

Returns true if the specified vertex is dead.

polyOp.getEdgeFaces <Poly poly> <int edge>

Returns the faces using the specified edge. Normally a 1 element (open edge) or 2 element array.

polyOp.getFaceDeg <Poly poly> <int face>

Returns the number of vertices in the specified face.

polyOp.getFaceMatID <Poly poly> <int face>

Returns the material ID assigned to the face

polyOp.setFaceMatID <Poly poly> <facelist> <int MatID>

Assigns the material ID to the face

polyOp.CollapseDeadStructs <Poly poly>

Removes all dead SO elements from the poly.

polyOp.getVert <Poly poly> <int vertex> node:<node=unsupplied>

Returns the position of the specified vertex. If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the position returned is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the return value is in the poly's local coordinate system.

polyOp.setVert <Poly poly> <vertlist> <point3 pos> node:<node=unsupplied>

Sets the position of the specified vertices. If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the position is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the position is in the poly's local coordinate system.

polyOp.moveVert <Poly poly> <vertlist> <point3 offset> node:<node=unsupplied>

Moves the specified vertices by <offset>. If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the offset is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the offset is in the poly's local coordinate system.

polyOp.isMeshFilledIn <Poly poly>

Returns true if all topological links, such as the list of edges, are complete for the poly.

polyOp.getEdgesUsingVert <Poly poly> <vertlist>

Bits in the result bitarray are set if the corresponding edge uses one of the vertices in <vertlist>.

polyOp.getFacesUsingVert <Poly poly> <vertlist>

Bits in the result bitarray are set if the corresponding face uses one of the vertices in <vertlist>.

polyOp.getVertsUsingEdge <Poly poly> <edgelist>

Bits in the result bitarray are set if the corresponding vertex uses one of the edges in <edgelist>.

polyOp.getFacesUsingEdge <Poly poly> <edgelist>

Bits in the result bitarray are set if the corresponding face uses one of the edges in <edgelist>.

polyOp.getVertsUsingFace <Poly poly> <facelist>

Bits in the result bitarray are set if the corresponding vertex uses one of the faces in <facelist>.

polyOp.getEdgesUsingFace <Poly poly> <facelist>

Bits in the result bitarray are set if the corresponding edge uses one of the faces in <facelist>.

polyOp.getElementsUsingFace <Poly poly> <facelist> fence:<fence_facelist>

Bits in the result bitarray are set for all faces in the same "element", or connected component, with faces in <facelist>.

If <fence_facelist> is specified, those faces will be considered "walls" for this processing and will not be evaluated. That is, if face i is specified in <facelist>, and a ring of faces around it is specified in <fence_facelist>, the algorithm will stop at that ring.

polyOp.getVertsUsedOnlyByFaces <Poly poly> <facelist>

Bits in the result bitarray are set if the corresponding vertex is only used by faces in <edgelist>.

polyOp.getFaceCenter <Poly poly> <int face> node:<node=unsupplied>

Returns the center of the face by taking the average of all its vertices. If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the position returned is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the return value is in the poly's local coordinate system.

polyOp.getSafeFaceCenter <Poly poly> <int face> node:<node=unsupplied>

Returns the "safe" center of the face, if possible. For non-convex faces, the average point found using getFaceCenter is unsuitable for some applications because it can lie outside the face completely, or in a region where it cannot see all the face's vertices (i.e., line segments from the center to the corner pass outside of the face.). If a safe center cannot be found, a value of UNDEFINED is returned.

This routine provides a better solution in some cases by finding the center of the convex hull of the face. The convex hull is defined as the region in a face with a clear line-of-sight to all the corners. Some faces, such as the top face in an extruded letter M, have an empty convex hull, in which case this routine fails and merely provides the regular center given by ComputeCenter.

If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the position returned is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the return value is in the poly's local coordinate system.

polyOp.getFaceNormal <Poly poly> <int face> node:<node=unsupplied>

Returns the face normal of the face. If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the direction vector returned is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the return value is in the poly's local coordinate system.

polyOp.getFaceArea <Poly poly> <int face>

Returns the area of the specified face.

polyOp.attach <Poly poly> <source> targetNode:<node=unsupplied> sourceNode:<node=unsupplied>

Attaches <source>, converted to a polymesh if necessary, to <poly>. If <source> or <poly> is not a node value, the corresponding targetNode or sourceNode must be specified. The source node is deleted after the attach is performed.

polyOp.deleteVerts <Poly poly> <vertlist>

Deletes the specified vertices.

polyOp.deleteFaces <Poly poly> <facelist> delIsoVerts:<boolean=true>

Deletes the specified faces. If <delIsoVerts> is true, any vertices that are no longer used by faces are also deleted.

polyOp.deleteEdges <Poly poly> <edgelist> delIsoVerts:<boolean=true>

Deletes the specified edges. If <delIsoVerts> is true, any vertices that are no longer used by edges are also deleted.

polyOp.weldVertsByThreshold <Poly poly> <vertlist>

Welds the specified vertices that are within the threshold distance. The threshold distance is a property (weldThreshold) of the editable poly. Only vertices on a border can be welded.

polyOp.weldVerts <Poly poly> <int vert1> <int vert2> <point3 location> node:<node=unsupplied>

Welds the two specified vertices, with the resulting vertex positioned at the specified location. Only vertices on a border can be welded.

If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the location is in the current coordinate system context.

If <poly> is an Editable Poly and <node> is not specified, the location is in the poly's local coordinate system.

polyOp.weldEdgesByThreshold <Poly poly> <edgelist>

Welds the vertices associated with the specified edges that are within the threshold distance. The threshold distance is a property (weldThreshold) of the editable poly. Only vertices on a border can be welded.

polyOp.weldEdges <Poly poly> <int edge1> <int edge2>

Welds the vertices associated with the specified edges. Only vertices on a border can be welded.

polyOp.createVert <Poly poly> <point3 pos> node:<node=unsupplied>

Creates a vertex as the specified position. If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the position is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the position is in the poly's local coordinate system. Returns the index of the created vertex or undefined if no vertex was created.

polyOp.createEdge <Poly poly> <int vert1> <int vert2>

Creates an edge using the two specified vertices. The vertices must be used by a common face. Returns the index of the created edge or undefined if no edge was created.

polyOp.createPolygon <Poly poly> <vertex array>

Creates a face using the specified vertices. The order of the vertices in the face is the order in the vertex array. For each successive vertex pair, at most 1 edge may exist between the vertices, and that edge must not go from the first to second vertex. The default triangulation for a face with the specified number of vertices is used; if the face is not convex, this triangulation may be inappropriate.

If this is the case, call retriangulate() on this face after it's created. This returns the index of the created face or undefined if no face was created.

polyOp.deleteIsoVerts <Poly poly>

Deletes any vertices not used by any faces.

polyOp.autoSmooth <Poly poly>

Performs an auto smooth of the poly. The face smoothing threshold angle is a property (autoSmoothThreshold) of the editable poly.

polyOp.flipNormals <Poly poly> <facelist>

Flips the normal of the specified faces.

polyOp.retriangulate <Poly poly> <facelist>

Retriangulates the specified faces.

polyOp.setDiagonal <Poly poly> <int face> <int face_vert1> <int face_vert2>

Sets a diagonal of the face between the two vertices. The face must have a degree greater than 3 and the two vertices must not be connected by an edge.

polyOp.forceSubdivision <Poly poly>

Forces an update of the surface subdivision at the next viewport redraw. Use when NURMS Subdivision is on and Update Options is Manually.

polyOp.meshSmoothByVert <Poly poly> <vertlist>

Smooths the faces associated with the specified vertices. Uses the smoothness, separateBySmoothing, and separateByMaterial properties of the editable poly.

polyOp.meshSmoothByFace <Poly poly> <facelist>

Smooths the specified faces. Uses the smoothness, separateBySmoothing, and separateByMaterial properties of the editable poly.

polyOp.meshSmoothByEdge <Poly poly> <edgelist>

Smooths the faces associated with the specified edges. Uses the smoothness, separateBySmoothing, and separateByMaterial properties of the editable poly.

polyOp.setFaceSmoothGroup <Poly poly> <facelist> <int smoothing_group> add:<boolean=false>

Sets the smoothing groups for the specified faces. The state of each bit in <smoothing_group> specifies whether the face belongs to the corresponding smoothing group. If <add> is true, <smoothing_group> is added to the existing smoothing group data specified for each face. If false, the existing smoothing group data is overwritten.

polyOp.getFaceSmoothGroup <Poly poly> <int face>

Returns the smoothing group data for the specified face as an integer. The state of each bit in the result specifies whether the face belongs to the corresponding smoothing group.

polyOp.breakVerts <Poly poly> <vertlist>

For each vertex in <vertlist>, N-1 new vertices are created at the same location, where N is the number of faces using that vertex. Each of these faces will use one of these vertices.

polyOp.divideEdge <Poly poly> <int edge> <float fraction>

Divides the specified edge at the specified fractional distance along the edge. The return value is the index of the new vertex or undefined if no vertex was created.

polyOp.divideFace <Poly poly> <int face> <point3 pos> node:<node=unsupplied>

Divides the specified face, with the new vertex being created at the closest point on the face to the specified position. If the specified position is outside the face, the vertex will be created at the center of the face. If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the position is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the position is in the poly's local coordinate system. Returns the index of the created vertex.

polyOp.collapseVerts <Poly poly> <vertlist>

Collapses each cluster of vertices in the specificed vertices to a single vertex. A vertex cluster is a set of vertices that are directly connected to one another.

polyOp.collapseFaces <Poly poly> <facelist>

Collapses the vertices associated with each cluster of faces in the specificed faces to a single vertex. A face cluster is a set of faces that are directly connected to one another.

polyOp.collapseEdges <Poly poly> <edgelist>

Collapses the vertices associated with each cluster of edges in the specificed edges to a single vertex. An edge cluster is a set of edges that are directly connected to one another.

polyOp.splitEdges <Poly poly> <edgelist>

Splits the specified edges at their middle.

polyOp.propagateFlags <Poly poly> <toSOLevel> <toFlag_int> <fromSOLevel> <fromFlag_int> ampersand:<boolean=false> set:<boolean=true> undoable:<boolean=true>

where toSOLevel/fromSOLevel = {#object | #vertex | #edge | #face}

Propogates component flags. For each <fromSOLevel> element that has flag <fromFlag_int> set, the <toSOLevel> elements that use or are used by the element will have their internal flag variable bits set based on <toFlag_int>. Only the bits corresponding to the bits that are set in <toFlag_int> are affected. If <ampersand> is false, and <fromFlag_int> has more than one bit set, the <fromSOLevel> elements will be tested to see if they have any of the corresponding bits set. If true, the <fromSOLevel> components elements be tested to see if they have all the corresponding bits set. If <set> is true, the <toSOLevel> elements have flags <toFlag_int> set. If false, these flags will be cleared instead.

If <undoable> is true, the operation in undoable, otherwise it is not. If bits 1 or 2 of <toFlag_int> are set (selected and dead flag bits), this operation is always undoable. Returns the number of <fromSOLevel> elements that tested positive for the <fromFlag_int> flags.

polyOp.tessellateByVert <Poly poly> <vertlist>

Tessellates the faces used by the specified vertices. Uses the tesselateBy and tessTension properties of the editable poly.

polyOp.tessellateByFace <Poly poly> <facelist>

Tessellates the specified faces. Uses the tesselateBy and tessTension properties of the editable poly.

polyOp.tessellateByEdge <Poly poly> <edgelist>

Tessellates the faces used by the specified edges. Uses the tesselateBy and tessTension properties of the editable poly.

polyOp.detachFaces <Poly poly> <facelist> delete:<boolean=true> asNode:<boolean=false> name:<string="Object01"> node:<node=unsupplied>

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 <asNode> is true, the faces are detached as a separate node. If <asNode> is false, the faces are detached as an element in the poly. If <asNode> is true, <name> specifies the name of the new node. If <asNode> is true and <poly> is an Editable Poly (not a node), <node> must be specified. Returns true if the operation was successful.

polyOp.detachEdges <Poly poly> <edgelist> delete:<boolean=true> asNode:<boolean=false> name:<string="Object01"> node:<node=unsupplied>

Detaches the faces used by the specified edges. If <delete> is true, the faces are deleted after being detached. If <delete> is false, the faces are not deleted. If <asNode> is true, the faces are detached as a separate node. If <asNode> is false, the faces are detached as an element in the poly. If <asNode> is true, <name> specifies the name of the new node. If <asNode> is true and <poly> is an Editable Poly (not a node), <node> must be specified. Returns true if the operation was successful.

polyOp.detachVerts <Poly poly> <vertlist> delete:<boolean=true> asNode:<boolean=false> name:<string="Object01"> node:<node=unsupplied>

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 <asNode> is true, the faces are detached as a separate node. If <asNode> is false, the faces are detached as an element in the poly. If <asNode> is true, <name> specifies the name of the new node. If <asNode> is true and <poly> is an Editable Poly (not a node), <node> must be specified. Returns true if the operation was successful.

polyOp.fillInMesh <Poly poly>

Recomputes the internal MNEdges and MNFace::edg, MNVert::edg, and MNVert::fac lists based on the information in the MNFace::vtx lists.

polyOp.resetSlicePlane <Poly poly>

Resets the slice plane.

polyOp.getSlicePlane <Poly poly> size:<&size_float_var> node:<node=unsupplied>

Returns the location and direction of the slice plane as a Ray value. If <size> is specified, the size of the slice plane is returned in the referenced variable. If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the ray returned is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the return value is in the poly's local coordinate system.

polyOp.setSlicePlane <Poly poly> <ray plane_and_dir> <float size> node:<node=unsupplied>

Sets the slice plane to the location and direction as specified by <plane_and_dir>, and the size as specified by <size>. If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the ray is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the ray is in the poly's local coordinate system.

polyOp.slice <Poly poly> <facelist> <ray plane_and_dir> node:<node=unsupplied>

Slices the poly based on the plane and direction as specified by <plane_and_dir>. If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, the ray is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, the ray is in the poly's local coordinate system. Uses the split property of the editable poly. Returns true if the slice was successful.

polyOp.inSlicePlaneMode <Poly poly>

Returns true if the editable poly is in slice mode, false otherwise.

polyOp.cutVert <Poly poly> <int start_vert> <point3 destination> <point3 projdir> node:<node=unsupplied>

If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, destination and projdir are in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, destination and projdir are in the poly's local coordinate system.

Returns the index of the new vertex if created, or undefined if no vertex was created.

polyOp.cutFace <Poly poly> <int face> <point3 start> <point3 destination> <point3 projdir> node:<node=unsupplied>

If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, start, destination, and projdir are in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, start, destination, and projdir are in the poly's local coordinate system.

Returns the index of the new vertex if created, or undefined if no vertex was created.

polyOp.cutEdge <Poly poly> <int edge1> <float prop1> <int edge2> <float prop2> <point3 projdir> node:<node=unsupplied>

If <poly> is a node, or if <poly> is an Editable Poly and <node> is specified, projdir is in the current coordinate system context. If <poly> is an Editable Poly and <node> is not specified, projdir is in the poly's local coordinate system.

Returns the index of the new vertex if created, or undefined if no vertex was created.

polyOp.capHolesByVert <Poly poly> <vertlist>

Finds any borders that use one or more of the specified vertices, and builds faces to cap the holes. Returns true if one or more holes were capped.

polyOp.capHolesByFace <Poly poly> <facelist>

Finds any borders that use one or more of the vertices associated with the specified faces, and builds faces to cap the holes. Returns true if one or more holes were capped.

polyOp.capHolesByEdge <Poly poly> <edgelist>

Finds any borders that use one or more of the vertices associated with the specified edges, and builds faces to cap the holes. Returns true if one or more holes were capped.

polyOp.makeVertsPlanar <Poly poly> <vertlist>

Moves the specified vertices so that they are planar.

polyOp.moveVertsToPlane <Poly poly> <vertlist> <Point3 planeNormal> <float planeOffset> node:<node>

Moves the specified vertices into the specified plane. The target plane is defined as all points which, when DotProducted with N, return offset. All vertices are moved along the normal vector N.

polyOp.makeEdgesPlanar <Poly poly> <edgelist>

Moves the vertices associated with the specified edges so that they are planar.

polyOp.moveEdgesToPlane <Poly poly> <edgelist> <Point3 planeNormal> <float planeOffset> node:<node=unsupplied>

Moves the vertices associated with the specified edges 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.

polyOp.makeFacesPlanar <Poly poly> <facelist>

Moves the vertices associated with the specified faces so that they are planar.

polyOp.moveFacesToPlane <Poly poly> <facelist> <Point3 planeNormal> <float planeOffset> node:<node=unsupplied>

Moves the vertices associated with the specified faces 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.

polyOp.createShape <Poly poly> <edgelist> smooth:<boolean=false> name:<string="Shape01"> node:<node=unsupplied>

Creates a shape node from the specified edges. If <smooth> is true, the shape is created as a smooth curve. The name of the new node is specified by <name>. If <poly> is an Editable Poly (not a node), <node> must be specified.

polyOp.extrudeFaces <Poly poly> <facelist> <float amount>

Extrudes the specified faces by the specified amount. Uses the extrustionType property of the Editable Poly.

polyOp.bevelFaces <Poly poly> <facelist> <float height> <float outline>

Bevels the specified faces. Extrudes the specified faces the specified height, and then scales the new top faces by <outline>. Uses the extrustionType property of the Editable Poly.

polyOp.chamferVerts <Poly poly> <vertlist> <float amount>

Chamfers the specified vertices by the specified amount.

polyOp.chamferEdges <Poly poly> <edgelist> <float amount>

Chamfers the specified edges by the specified amount.

The following methods are specific to mapping. All channels are 0-based.

polyOp.setNumMaps <Poly poly> <int count> keep:<boolean=true>

Sets the number of map channels available. The number of map channels can be set from 0 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.

polyOp.getNumMaps <Poly poly>

Returns the number of map channels available as an <integer>.

polyOp.setMapSupport <Poly poly> <int mapChannel> <Boolean support>

Sets whether the specified mapping channel is supported or not. If <support> is true, and the channel support state is currently false, a new map face array of the same size as the number of faces in the mesh is allocated, but no map vertex array is allocated. If <support> is false, and the channel support state is currently true, existing map channel face and vertex arrays are deallocated. If <support> and the current channel support state are both the same, no action is performed. SetNumMaps() is automatically called if the specified map channel is not available. <mapChannel> index values are 0-based, with Map channels 0 and 1 being the Vertex Color and default Texture Map channels.

polyOp.getMapSupport <Poly poly> <int mapChannel>

Returns whether the specified map channel is supported. This signifies that a map face array is present, but not necessarily a map vertex array.

polyOp.setNumMapVerts <Poly poly> <int mapChannel> <int count> keep:<boolean=false>

Sets the number of vertices for the map channel, initializing the map vertex array. If <keep> is false, the old map vertex information is discarded. If true, the old map vertex information is retained after the resize.

polyOp.getNumMapVerts <Poly poly> <int mapChannel>

Returns the number of vertices for the map channel as an <integer>.

polyOp.setNumMapFaces <Poly poly> <int mapChannel> <int count> keep:<boolean=false>

Sets the number of faces for the map channel. If keep is false, the old map face information is discarded. If true, the old map face information is retained after the resize. Dangerous to use with map channels 0 and 1.

polyOp.getNumMapFaces <Poly poly> <int mapChannel>

Returns the number of faces for the map channel as an <integer>.

polyOp.setMapVert <Poly poly> <int mapChannel> <int index> <Point3 uvw>

Sets the coordinates of the specified map vertex.

polyOp.getMapVert <Poly poly> <int mapChannel> <int index>

Returns the coordinates of the specified map vertex as a <point3>.

polyOp.setMapFace <Poly poly> <int mapChannel> <int map face index> <map vertex array>

Sets the map vertices for the specified map face.

polyOp.getMapFace <Poly poly> <int mapChannel> <int index>

Returns the vertex indices of the specified map face as an array.

polyOp.defaultMapFaces <Poly poly> <int mapChannel>

Allocates and initializes a basic planar map, or a white map for the vertex color hannel.

polyOp.applyUVWMap <Poly poly>

<#planar | #cylindrical | #spherical | #ball | #box> | <#face>

utile:<float=1.0> vtile:<float=1.0> wtile:<float=1.0>

uflip:<boolean=false> vflip:<boolean=false> wflip:<boolean=false>

cap:<boolean=true> tm:<Matrix3=identity matrix> channel:<integer=1>

Applies the specified mapping type to the mapping channel.

utile/vtile/wtile - Number of tiles in the U/V/W directions.

uflip/vflip/wflip - U/V/W are mirrored if true.

cap - used with #cylindrical. If true, then any face normal that is pointing more vertically than horizontally will be mapped using planar coordinates.

tm - defines the mapping space. As each point is mapped, it is multiplied by this matrix, and then it is mapped.

channel - the mapping channel the mapping is applied to, defaults to channel 1.

polyOp.getVertsByColor <Poly poly> <Color color> <Float red_thresh> <Float green_thresh> <Float blue_thresh> channel:<int=0>

Returns the vertices whose vertex color is within the color range as a <bitarray>. The range values should be in the range of 0 to 255.

polyOp.getVertsByColor <Poly poly> <Point3 uvw> <Float u_thresh> <Float v_thresh> <Float w_thresh> channel:<int=0>

Returns the vertices whose UVW is within the UVW range as a <bitarray>. The range values should be in the range of 0 to 1.

polyOp.setVertColor <Poly poly> <int mapChannel> <vertlist> <Color color>

Sets the vertex color for the specified vertices in the specified <mapChannel>.

polyOp.SetFaceColor <Poly poly> <int mapChannel> <facelist> <Color color>

Sets the vertex color for the vertices used by the specified faces in the specified <mapChannel>.

polyOp.setNumVDataChannels <Poly poly> <int count> keep:<boolean=true>

Sets the number of vertex data channels available. The number of vertex data channels can be set from 0 to 100.

If <keep> is false, the old channel data is discarded. If true, the old channel data is retained after the resize. The first ten channels for Discreet's use only.

channel 1: Soft Selection

channel 2: Vertex weights (for NURMS MeshSmooth)

channel 3: Vertex Alpha values

channel 4: Cornering values for subdivision use

polyOp.getNumVDataChannels <Poly poly>

Returns the number of vertex data channels available as an <integer>.

polyOp.setVDataChannelSupport <Poly poly> <int vdChannel> <boolean support>

Sets whether the specified vertex data channel is supported or not. <vdChannel> index values are 1-based, The first ten channels for Discreet's use only.

channel 1: Soft Selection

channel 2: Vertex weights (for NURMS MeshSmooth)

channel 3: Vertex Alpha values

channel 4: Cornering values for subdivision use

polyOp.getVDataChannelSupport <Poly poly> <int vdChannel>

Returns whether the specified vertex data channel is supported.

polyOp.getVDataValue <Poly poly> <int vdChannel> <int vertex_index>

Returns the floating point data value associated with vertex vertex_index in vertex data channel <vdChannel> as a <float>.

polyOp.setVDataValue <Poly poly> <int vdChannel> <vertlist> <float>

Sets the floating point data value associated with the specified vertices in vertex data channel <vdChannel>.

polyOp.freeVData <Poly poly> <int vdChannel>

polyOp.resetVData <Poly poly> <int vdChannel>

Deallocates the existing vertex data channel and turns off the vertex data channel support state. These methods do the exact same thing.

polyOp.setNumEDataChannels <Poly poly> <int count> keep:<boolean=true>

Sets the number of edge data channels available. The number of edge data channels can be set from 0 to 100.

If <keep> is false, the old channel data is discarded. If true, the old channel data is retained after the resize. The first two channels for Discreet's use only.

channel 1: edge knot data

channel 2: edge crease data

polyOp.getNumEDataChannels <Poly poly>

Returns the number of edge data channels available as an <integer>.

polyOp.setEDataChannelSupport <Poly poly> <int edChannel> <Boolean support>

Sets whether the specified edge data channel is supported or not. <edChannel> index values are 1-based, the first two channels for Discreet's use only.

channel 1: edge knot data

channel 2: edge crease data

polyOp.getEDataChannelSupport <Poly poly> <int edChannel>

Returns whether the specified edge data channel is supported.

polyOp.getEDataValue <Poly poly> <int edChannel> <int edge_index>

Returns the floating point data value associated with edge edge_index in edge data channel <edChannel> as a <float>.

polyOp.setEDataValue <Poly poly> <int edChannel> <edgelist> <float>

Sets the floating point data value associated with the specified edges in edge data channel <edChannel>.

polyOp.freeEData <Poly poly> <int edChannel>

resetEData <Poly poly> <int edChannel>

Deallocates the existing edge data channel and turns off the edge data channel support state. These methods do the exact same thing.


Modifier : MAXWrapper and SpacewarpModifier : MAXWrapper

The Modifier and SpacewarpModifier families of classes can be created and added to an object's modifier stack using the addModifier() or modPanel.addModToSelection() methods. Unless otherwise noted, the term modifier will be used to mean members of either class.

By making a single modifier and adding it to several objects, you are sharing the modifier between the objects, as you would by applying a modifier to a selection of objects in the 3ds max user interface. The constructors in the following classes can take any of the listed properties as optional keyword arguments with the defaults as shown.

Existing modifiers can be accessed in two ways:

  • As a property access on a <node>. When you access a property on a <node> scene object, such as its name or position, or length, MAXScript will also consider modifiers on the object to be properties, for example:

$box1.heightsegs -- get creation parameter

$box1.twist -- get the twist modifier

$box1.twist.angle -- the twist's angle

You can then access modifier properties as subproperties on the modifier as shown. If the modifier name has spaces in it, you can use the '_' as space convention that pathnames use, like this:

$box1.uvw_map -- to get the 'UVW Map' modifier

  • This will work in simple situations, but there may be several modifiers with the same name, or a modifier with the same name as a creation parameter (which is always looked for first). In this situation you can use the modifier array mechanism, which yields an array of modifiers you can index into:

$box1.modifiers -- get modifier array

$box1.modifiers[3] -- get the 3rd down the list

$box1.modifiers[#twist] -- get the one named "twist"

$box1.modifiers["ffd 4x4x4"] -- get the FFD

As you can see from the examples, you can use both name literals and strings to index modifiers by name in the table, so this is a way to get at modifiers with characters you cannot use in a MAXScript property name.

The ordering is as you would see in the Modify panel, numbered starting at 1 from top-to-bottom.

The classes derived directly from the Modifier and SpacewarpModifier classes are described in Modifier and SpacewarpModifier Types.

The properties, operators, and methods that are common to all classes derived directly from the Modifier and SpacewarpModifier classes are described in Modifier Common Properties, Operators, and Methods.

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 MAXWrapper Common Properties, Operators, and Methods.


Modifier Common Properties, Operators, and Methods

Properties

All modifiers have the following properties:

<modifier>.name : string

get and set modifier name

<modifier>.enabled : boolean

<modifier>.enabledInViews : boolean

lets you control the modifier's enabled/disabled state. These are read/write properties that let you determine and set the enabled state of the given modifier, for example:

$foo.modifiers[2].enabled = false -- turn off 2nd modifier

The enabledInViews property controls viewport display, enabled controls both viewport and rendered display.

Associated Methods

The modifier stack on a scene node can be manipulated using the following <node> methods:

validModifier ( <node> | <objectset>) <modifier>

Tests whether a particular modifier may be added the given <node> or <objectset>. Returns true if so, false if not.

The validModifier() method operates exactly as does the Modify panel in determining modifier applicability. Any modifier that takes a deformable object will return true for all scene objects except Helpers. This corresponds to the Modify panel's behavior of allowing modifiers such as Bend, Taper, etc. to be applied to lights and cameras, space warp objects, etc., as well as geometry types like box, sphere, etc., but not helpers such as dummys or bones.

addModifier <node> <modifier> [before:index] -- mapped

adds the modifier to all instances of the node to which the function is applied. The optional before: keyword argument can be used to insert the modifier into the node's modifier stack just before the indexed modifier, counting from the top of the stack. The added modifier will apply to any appropriate active sub-object selection in the node only if the node is currently selected and open in the Modify panel at the desired sub-object level. You can use the 3ds max System global variable, subObjectLevel to test and set the level for the object currently open in the Modify panel. For example:

max modify mode -- open mod panel

select $box01 -- select box01 into mod panel

subObjectLevel = 3 -- subobject level to Face

addModifier $box01 (ffd_2x2x2()) -- add FFD mod to those faces

If the before: keyword argument would place a modifier in an invalid position in the stack, the modifier will be placed at the nearest valid position. For example, if you tried to place a SpacewarpModifier class object below a Modifier class object, the SpacewarpModifier object would be placed below any SpacewarpModifier objects, and above any Modifier objects.

If <node> is a collection, an instance of the modifier is placed on each of the nodes in the collection. Unlike interactively applying a modifier to a selection, the position and size of each modifier instance's gizmo corresponds to position and size of the node the modifier instance is applied to. To apply a modifier to a collection in the same manner that 3ds max applies modifiers, use the modPanel.addModToSelection() described in Modify Panel.

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.

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 for more details.

getModContextTM <node> <modifier>

Returns a Matrix3 value giving the modifier's context transform for the local coordinates used in modifier sub-object gizmos. Accessing the transform properties of a modifier sub-object such as a gizmo or a center in MAXScript yields values that are relative to that modifier's context transform, equivalent to the values shown in track view for those properties. If the modifier is not operating on a sub-object selection, such as a face or vertex selection, or if the modifier was interactively applied to an object selection, this context TM is the local coordinate space of the object itself. However, if the modifier is operating on either an object selection set or a sub-object selection, the context transform gives the position and orientation of that selection, and so you can use getModContextTM() to get the world-space transform properties of any of its sub-objects.

getModContextBBoxMin <node> <modifier>

getModContextBBoxMax <node> <modifier>

These functions complement the getModContextTM() function and can be used to derive the world-space coordinates of the bounding box of the modifier context. This can be used, for example, to determine the bounds of a modifier operating on a sub-selection or the bounds of an FFD lattice. This is particularly useful for scripting FFD control point placement, since these control points live in a 0-to-1 lattice space—the mod context bounding box gives the world space bounds of this lattice space allowing you to compute scaled lattice space coordinates from world coordinates. The functions return Point3 values for the minimum and maximum extents of the bounding box.

See also

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

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 Scripting Vertex and Control Point Animation). 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 Modifier Common Properties, Operators, and Methods. An example 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

Bend

Bevel

Bevel_Profile

CameraMap

Cap_Holes

CrossSection

DeleteMesh

DeleteSpline

Disp_Approx

Displace_Mesh

Edit_Mesh

Edit_Patch

Edit_Spline

Extrude

Face_Extrude

FFDBox

FFDCyl

FFD_2x2x2

FFD_3x3x3

FFD_4x4x4

FFD_Select

Fillet_Chamfer

Flex

Lathe

Lattice

Linked_XForm

MaterialByElement

Material

Melt

MeshSmooth

Mesh_Select

Mirror

Morpher

NCurve_Sel

Noise

Normalize_Spline

Normal

NSurf_Sel

Optimize

PatchDeform

PathDeform

Preserve

Push

Relax

Ripple

Skew

Skin

Slice

Smooth

Spherify

SplineSelect

Squeeze

STL_Check

Stretch

Substitute

Surface

SurfDeform

Taper

Tesselate

Trim_Extend

Twist

Unwrap_UVW

UVWMap

UVW_XForm

Vertex_Colors

VertexPaint

VolumeSelect

Wave

XForm

SpacewarpModifier

The SpacewarpModifier classes are separated into two groups. The first group are those classes that bind a node to a SpaceWarp 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

BombBinding

DeflectorBinding

DisplaceBinding

FFD_Binding

GravityBinding

MotorMod

PathFollowMod

PBombMod

PDynaFlectMod

POmniFlectMod

PushMod

RippleBinding

SDeflectMod

SDynaFlectMod

SOmniFlectMod

SpaceConform

UDeflectorMod

UDynaFlectMod

UOmniFlectMod

WaveBinding

WindBinding

Other SpacewarpModifiers

Displace_Mesh

Displace_NURBS

MapScaler

SpaceCameraMap

SpacePatchDeform

SpacePathDeform

SpaceSurfDeform

Surface_Mapper


Affect_Region : Modifier

Constructor

affect_region ...

Properties

<Affect_Region>.falloff Float default: 20.0 -- animatable

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry.

<Affect_Region>.Pinch Float default: 0.0 -- animatable

Raises and lowers the top point of the curve along the vertical axis. Sets the relative "pointedness" of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis.

<Affect_Region>.Bubble Float default: 0.0 -- animatable

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

<Affect_Region>.ignoreBackfacing Boolean default: off

When on, affects only those vertices whose face normals are in the same general direction as the gizmo arrow. When turned off, all vertices in the Falloff group are affected.

<Affect_Region>.start_point Point3 default: [0,0,0] -- animatable

The starting point for the application of the affect region.

<Affect_Region>.end_point Point3 default: [0,0,25] – animatable

The end point for application of the affect region.

Methods

AffectRegionVal <distance> <falloff> <pinch> <bubble>

The standard affect region function, based on a distance and the three affect region parameters (same as the editable mesh). This function is a cubic curve which returns 1 at distance 0, 0 if distance is greater than falloff, and other values for distance between 0 and falloff.

Notes

The Ignore Back Facing property is not accessible to MAXScript in 3ds max 4.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Bend : Modifier

Constructor

bend ...

Properties

<Bend>.angle Float default: 0.0 -- animatable

The angle to bend from the vertical plane.

<Bend>.direction Float default: 0.0 -- animatable

The direction of the bend relative to the horizontal plane.

<Bend>.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:

0- X

1- Y

2- Z

<Bend>.limit Boolean default: false

When on, applies limit constraints to the bend effect.

<Bend>.upperlimit Float default: 0.0 -- animatable, alias: Upper_Limit

The upper boundary in world units from the bend center point beyond which the bend no longer affects geometry.

<Bend>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit

The lower boundary in world units from the bend center point beyond which the bend no longer affects geometry.

<Bend>.center Point3 default: [0,0,0] -- animatable

You can translate and animate the center, altering the Bend gizmo's shape, and thus the shape of the bent object.

<Bend>.gizmo SubAnim

You can transform and animate the gizmo like any other object, altering the effect of the Bend modifier.

<Bend.gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the gizmo object. Translating the gizmo translates its center an equal distance.

<Bend.gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the gizmo object. Rotating the gizmo takes place with respect to its center.

<Bend.gizmo>.scale Point3 default: [1,1,1] -- animatable

The scaling of the gizmo object. Scaling the gizmo takes place with respect to its center.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Bevel : Modifier

Constructor

bevel ...

Properties

<Bevel>.Cap_Bottom Integer default: 1

When on, caps the end with the lowest local Z value (bottom) of the object. When turned off, the bottom is open.

0- Off

1- On

<Bevel>.Cap_Top Integer default: 1

When on, caps the end with the highest local Z value (top) of the object. When turned off, the end is left open.

0- Off

1- On

<Bevel>.Cap_Type Integer default: 0

Sets cap type:

0- Morph (Creates cap faces suitable for morphing.)

1- Grid (Creates cap faces in a grid pattern. This cap type deforms and renders better than morph capping.)

<Bevel>.Side_Type Integer default: 0

Side type:

0- Linear Sides (Segment interpolation between levels follows a straight line.)

1- Curved Sides (Segment interpolation between levels follows a Bezier curve.)

<Bevel>.segments Integer default: 1 -- animatable

The number of intermediate segments between each level.

<Bevel>.Smooth_Levels Integer default: 0

Controls whether smoothing groups are applied to the sides of a beveled object. Caps always use a different smoothing group than the sides. When turned on, smoothing groups are applied to the sides, and the sides appear rounded. When turned off, smoothing groups are not applied, and the sides appear as flat bevels.

0- Off

1- On

<Bevel>.Produce_Mapping_Coords Integer default: 0

When turned on, mapping coordinates are applied to the beveled object.

0- Off

1- On

<Bevel>.Keep_Lines_From_Crossing Integer default: 0

When on, this prevents outlines from crossing over themselves. This is accomplished by inserting extra vertices in the outline and replacing sharp corners with a flat line segment.

0- Off

1- On

<Bevel>.Separation_Between_Lines Float default: 1.0 -- animatable

The distance to be maintained between edges.

<Bevel>.Starting_Outline Float default: 0.0 -- animatable

The distance the outline is offset from the original shape. A non-zero setting changes the original shape's size. Positive values make the outline larger and negative values make the outline smaller.

<Bevel>.Level_1_Height Float default: 0.0 -- animatable

The distance of Level 1 above the Start level.

<Bevel>.Level_1_Outline Float default: 0.0 -- animatable

The distance to offset the Level 1 outline from the Start Outline.

<Bevel>.Use_Level_2 Integer default: 0

Adds a level after Level 1 when on.

0- Off

1- On

<Bevel>.Level_2_Height Float default: 0.0 -- animatable

The distance above Level 1.

<Bevel>.Level_2_Outline Float default: 0.0 -- animatable

The offset distance of the Level 2 outline from Level 1.

<Bevel>.Use_Level_3 Integer default: 0

Adds a level after the previous level. If Level 2 is not on, Level 3 is added after Level 1.

0- Off

1- On

<Bevel>.Level_3_Height Float default: 0.0 -- animatable

The distance above the previous level.

<Bevel>.Level_3_Outline Float default: 0.0 -- animatable

The offset distance of Level 3 from the previous level.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Bevel_Profile : Modifier

Constructor

bevel_profile ...

Properties

<Bevel_Profile>.Produce_Mapping_Coords Integer default: 0

When on, assigns UV coordinates.

0- Off

1- On

<Bevel_Profile>.Cap_Bottom Integer default: 1

When on, caps the end with the lowest local Z value (bottom) of the object. When turned off, the bottom is open.

0- Off

1- On

<Bevel_Profile>.Cap_Top Integer default: 1

When on, caps the end with the highest local Z value (top) of the object. When turned off, the end is left open.

0- Off

1- On

<Bevel_Profile>.Cap_Type Integer default: 0

Cap type:

0- Morph (Selects a deterministic method of capping that provides the same number of vertices for morphing between objects.)

1- Grid (Creates gridded caps that are better for cap deformations.)

<Bevel_Profile>.Keep_Lines_From_Crossing Integer default: 0

When on, prevents beveled surfaces from self intersecting. This requires more processor calculation and can be time-consuming in complex geometry.

0- Off

1- On

<Bevel_Profile>.Separation_Between_Lines Float default: 1.0 -- animatable

The distance that sides should be kept apart to prevent intersections.

<Bevel_Profile>.profile_gizmo SubAnim

You can move, scale, and rotate the gizmo to alter the effect of the bevel profile modifier on the object.

<Bevel_Profile.Profile_Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the profile gizmo.

<Bevel_Profile.Profile_Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the profile gizmo.

<Bevel_Profile.Profile_Gizmo>.scale Point3 default: [1,1,1] -- animatable

The scale of the profile gizmo.

Notes

There is no way to set the Profile shape using MAXScript in 3ds max 4.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Camera_Map : Modifier

Constructor

cameraMap ...

Properties

There are no additional properties for CameraMap.

Notes

To set the camera and channel, use the CameraMap interfaces:.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Cap_Holes : Modifier

Constructor

cap_holes ...

Properties

<Cap_Holes>.Smooth_New_Faces Integer default: 1

When on, assigns the same smoothing group number to all new faces. If possible, this will be a smoothing group number not used elsewhere in the object.

0- Off

1- On

<Cap_Holes>.Smooth_With_Old_Faces Integer default: 0

Smoothes new triangular faces using the smoothing groups from bordering old faces. This smoothes only one level in from the perimeter of the border of the hole, so you might need to use both this and the Smooth New Faces option to properly smooth a large hole.

0- Off

1- On

<Cap_Holes>.Make_All_New_Edges_Visible Integer default: 0

When on, makes all of the edges visible in the new faces.

0- Off

1- On

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


CrossSection : Modifier

Constructor

crossSection ...

Properties

There are no additional properties for CrossSection.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


DeleteMesh : Modifier

Constructor

deleteMesh ...

Properties

There are no additional properties for DeleteMesh.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


DeleteSplineModifier : Modifier

Constructor

deleteSplineModifier ...

Properties

There are no additional properties for DeleteSplineModifier.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Disp_Approx : Modifier

Constructor

disp_Approx ...

Properties

There are no additional properties for Disp_Approx.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Displace : Modifier

Constructor

displace ...

Properties

<Displace>.strength Float default: 0.0 -- animatable

When set to 0.0, Displace has no effect. Values greater than 0.0 displace object geometry or particles away from the position of the gizmo. Values less than 0.0 displace geometry toward the gizmo.

<Displace>.decay Float default: 0.0 -- animatable

Varies the displacement strength with distance. By default, Displace has the same strength throughout world space. Increasing Decay causes the displacement strength to diminish as distance increases from the position of the Displace gizmo. This has the effect of concentrating the force field near the gizmo, similar to the field around a magnet repelling its opposite charge.

<Displace>.lumCenterEnable Boolean default: false

When on, the software uses .center to determine which level of gray Displace uses as the zero displacement value.

<Displace>.center Float default: 0.5 -- animatable, alias: lumCenter

By default, Displace centers the luminance by using medium (50 percent) gray as the zero displacement value. Gray values greater than 128 displace in the outward direction (away from the Displace gizmo) and gray values less than 128 displace in the inward direction (toward the Displace gizmo). This value adjusts the default. With a Planar projection, the displaced geometry is repositioned above or below the Planar gizmo.

<Displace>.bitmap Bitmap default: undefined

This bitmap is used for displacement.

<Displace>.map TextureMap default: undefined

This texture map is used for displacement.

<Displace>.blur Float default: 0.0 -- animatable

Blurs or softens the effect of the bitmapped displacement by increasing the value.

<Displace>.maptype Integer default: 0

Type of map projection:

0- Planar (Projects the map from a single plane.)

1- Cylindrical (Projects the map as if it were wrapped around the cylinder.)

2- 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.)

3- 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>.cap Boolean default: false

When on, a copy of the map is projected from the ends of the cylinder.

<Displace>.length Float default: 1.0 -- animatable

The length of the displace gizmo's bounding box.

<Displace>.width Float default: 1.0 -- animatable

The width of the displace gizmo's bounding box.

<Displace>.height Float default: 1.0 -- animatable

The height of the displace gizmo's bounding box.

Height has no effect on Planar mapping.

<Displace>.U_Tile Float default: 1.0 -- animatable

The number of times the bitmap repeats along the U-axis.

<Displace>.U_Flip Boolean default: false

When on, reverses the orientation of the map along the U-axis.

<Displace>.V_Tile Float default: 1.0 -- animatable

The number of times the bitmap repeats along the V-axis.

<Displace>.V_Flip Boolean default: false

When on, reverses the orientation of the map along the V-axis.

<Displace>.W_Tile Float default: 1.0 -- animatable

The number of times the bitmap repeats along the W-axis.

<Displace>.W_Flip Boolean default: false

When on, reverses the orientation of the map along the W-axis.

<Displace>.useMap Boolean default: false

When on, has Displace use the UV mapping set earlier in the stack. This has no effect if the object is not mapped.

<Displace>.applyMap Boolean default: false

When on, applies the Displace UV mapping to the bound object. This lets you apply material maps to the object using the same mapping coordinates as the modifier.

<Displace>.Map_or_Vertex_Color Integer default: 0

Specifies whether to apply the displacement projection to a mapping channel or a vertex color channel:

0- Map Channel

1- Vertex Color Channel

<Displace>.Map_Channel Integer default: 1

The map channel to use for displacement projection.

<Displace>.axis Integer default: 2

Flips the alignment of the mapping gizmo along one of its three axes:

0- X

1- Y

2- Z

<Displace>.gizmo SubAnim

You can move, scale, and rotate the gizmo to alter the effect of the displacement modifier on the object.

<Displace.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the displace gizmo.

<Displace.Gizmo>.rotation Quat default: (quat 0 0 -1 0) -- animatable

The rotation of the displace gizmo.

<Displace.Gizmo>.scale Point3 default: [1,1,1] -- animatable

The scaling of the displace gizmo.

Notes

The Gizmo property is not present until the Displace modifier has been applied to a node.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Edit_Mesh : Modifier

Constructor

edit_mesh ...

Properties

There are no additional properties for Edit_Mesh.

See the getVertSelection(), getFaceSelection(), and getEdgeSelection() functions in Editable_Mesh for information about accessing the current selections in the Edit_Mesh modifier.

See the Editable Mesh Modify Panel Command Modes and Operations section in Editable_Mesh for information on invoking the various Edit_Mesh operations.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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 Patch for information on invoking the various Edit_Patch operations.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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 SplineShape for information on invoking the various Edit_Spline operations.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Extrude : Modifier

Constructor

extrude ...

Properties

<Extrude>.amount Float default: 25.0 -- animatable

The depth of the extrusion.

<Extrude>.segs Integer default: 1 -- animatable, alias: segments

The number of segments that will be created in the extruded object.

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

0- 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.)

1- 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:

0- Patch (Produces an object that you can collapse to a patch object.)

1- Mesh (Produces an object that you can collapse to a mesh object.)

2- NURBS (Produces an object that you can collapse to a NURBS surface.)

<Extrude>.matIDs Boolean 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>.useShapeIDs Boolean default: false

When on, the software uses the material ID values assigned to segments in the modified object.

<Extrude>.smooth Boolean 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.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


FFD_Box : Modifier

Constructor

ffdBox ...

Properties

<FFDBox>.dispLattice Boolean default: true -- alias: Lattice

Draws lines connecting the control points to make a grid.

<FFDBox>.dispSource Boolean default: false—alias: Source_Volume

Displays the control points and lattice in their unmodified state.

<FFDBox>.deformType Integer default: 0

deformType = 0 - Only In Volume; 1 - All Vertices

<FFDBox>.falloff Float default: 0.0 -- animatable

Determines the distance from the lattice that the FFD effect will decrease to zero.

<FFDBox>.tension Float default: 25.0 -- animatable

Adjusts the tension of the deformation splines.

<FFDBox>.continuity Float default: 25.0 -- animatable

Adjusts the continuity of the deformation splines.

<FFDBox>.inPoints Boolean default: true -- alias: Inside_Points

Only control points inside the object are affected by Conform to Shape.

<FFDBox>.outPoints Boolean default: true -- alias: Outside_Points

Only control points outside the object are affected by Conform to Shape.

<FFDBox>.offset Float default: 0.05 -- animatable

The distance by which control points affected by Conform to Shape are offset from the object surface.

<FFDBox>.lattice_transform SubAnim

<FFDBox.lattice_transform>.position Point3 default: [0,0,0] -- animatable

<FFDBox.lattice_transform>.rotation Quat default: (quat 0 0 0 1) -- animatable

<FFDBox.lattice_transform>.scale Point3 default: [1,1,1] -- animatable

Methods

conformToShape <FFDBox>

conforms the control points of the FFD to the node the FFD is applied to. If an instance of the FFD modifier has been applied to more than one object, no action is performed.

resetLattice <FFDBox>

resets the control points of the FFD to their default positions.

getDimensions <FFDBox>

setDimensions <FFDBox> <Point3>

Get and set the number of control points for the FFDBox modifier. The first component value in the Point3 specifies the number of Width control points, the second the number of Length control points, and the third the number of Height control points. The minimum value for each component value is 2.

animateVertex <FFDBox> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where <control_point_spec> is one of:

<integer_index>

<integer_index_array>

#all

By assigning controllers to the control points, the control points are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the control points. For example,

animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword #all to animate all control points.

See also Class and Object Inspector Functions and Scripting Vertex and Control Point Animation for details on accessing the control points in an FFD and Modifier Sub-Object Transform Properties for details on the coordinate system used for FFD control points.

animateAll <FFDBox>

Applies controllers to all control points of the FFD modifier.

Notes

The default number of control points in a FFDBox created by MAXScript is 4x4x4.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Class and Object Inspector Functions

Scripting Vertex and Control Point Animation

Modifier Sub-Object Transform Properties


FFD_Cyl : Modifier

Constructor

ffdCyl ...

Properties

<FFDCyl>.dispLattice Boolean default: true -- alias: Lattice

Draws lines connecting the control points to make a grid.

<FFDCyl>.dispSource Boolean default: false—alias: Source_Volume

Displays the control points and lattice in their unmodified state.

<FFDCyl>.deformType Integer default: 0

Deform type:

0- Only In Volume (Deforms vertices that lie inside the source volume. Vertices outside the source volume are not affected.)

1- All Vertices (Deforms all vertices regardless of whether they lie inside or outside the source volume depending on the value in the Falloff spinner. The deformation outside the volume is a continuous extrapolation of the deformation inside the volume. Note that the deformation can be extreme for points far away from the source lattice.)

<FFDCyl>.falloff Float default: 0.0 -- animatable

Determines the distance from the lattice that the FFD effect will decrease to zero.

<FFDCyl>.tension Float default: 25.0 -- animatable

Adjusts the tension of the deformation splines.

<FFDCyl>.continuity Float default: 25.0 -- animatable

Adjusts the continuity of the deformation splines.

<FFDCyl>.inPoints Boolean default: true -- alias: Inside_Points

Only control points inside the object are affected by Conform to Shape.

<FFDCyl>.outPoints Boolean default: true -- alias: Outside_Points

Only control points outside the object are affected by Conform to Shape.

<FFDCyl>.offset Float default: 0.05 -- animatable

The distance by which control points affected by Conform to Shape are offset from the object surface.

<FFDCyl>.lattice_transform SubAnim

<FFDCyl.lattice_transform>.position Point3 default: [0,0,0] -- animatable

<FFDCyl.lattice_transform>.rotation Quat default: (quat 0 0 0 1) -- animatable

<FFDCyl.lattice_transform>.scale Point3 default: [1,1,1] -- animatable

Methods

conformToShape <FFDCyl>

conforms the control points of the FFD to the node the FFD is applied to. If an instance of the FFD modifier has been applied to more than one object, no action is performed.

resetLattice <FFDCyl>

resets the control points of the FFD to their default positions.

getDimensions <FFDCyl>

setDimensions <FFDCyl> <Point3>

sets the number of control points for the FFDCyl modifier. The first component value in the Point3 specifies the number of Side control points, the second the number of Radial control points, and the third the number of Height control points. The minimum component values are 6, 2, and 2, respectively.

animateVertex <FFDCyl> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where <control_point_spec> is one of:

<integer_index>

<integer_index_array>

#all

By assigning controllers to the control points, the control points are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the control points. For example,

animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword #all to animate all control points.

See also Class and Object Inspector Functions and Scripting Vertex and Control Point Animation for details on accessing the control points in an FFD and Modifier Sub-Object Transform Properties for details on the coordinate system used for FFD control points.

animateAll <FFDCyl>

Applies controllers to all control points of the FFD modifier.

Notes

The default number of control points in a FFDCyl created by MAXScript is always 4x6x4.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Class and Object Inspector Functions

Scripting Vertex and Control Point Animation

Modifier Sub-Object Transform Properties


FFD_2x2x2 : Modifier

Constructor

ffd_2x2x2 ...

Properties

<FFD_2x2x2>.dispLattice Boolean default: true -- alias: Lattice

Draws lines connecting the control points to make a grid.

<FFD_2x2x2>.dispSource Boolean default: false—alias: Source_Volume

Displays the control points and lattice in their unmodified state.

<FFD_2x2x2>.deformType Integer default: 0

Deform type:

0- Only In Volume (Deforms vertices that lie inside the source volume. Vertices outside the source volume are not affected.)

1- All Vertices (Deforms all vertices, regardless of whether they lie inside or outside the source volume.)

<FFD_2x2x2>.inPoints Boolean default: true -- alias: Inside_Points

Only control points inside the object are affected by Conform to Shape.

<FFD_2x2x2>.outPoints Boolean default: true -- alias: Outside_Points

Only control points outside the object are affected by Conform to Shape.

<FFD_2x2x2>.offset Float default: 0.05 -- animatable

The distance by which control points affected by Conform to Shape are offset from the object surface.

<FFD_2x2x2>.lattice_transform SubAnim

<FFD_2x2x2.lattice_transform>.position Point3 default: [0,0,0] -- animatable

<FFD_2x2x2.lattice_transform>.rotation Quat default: (quat 0 0 0 1) -- animatable

<FFD_2x2x2.lattice_transform>.scale Point3 default: [1,1,1] -- animatable

Notes

The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4.

Methods

conformToShape <FFD_2x2x2>

conforms the control points of the FFD to the node the FFD is applied to. If an instance of the FFD modifier has been applied to more than one object, no action is performed.

resetLattice <FFD_2x2x2>

resets the control points of the FFD to their default positions.

animateVertex <FFD_2x2x2> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where <control_point_spec> is one of:

<integer_index>

<integer_index_array>

#all

By assigning controllers to the control points, the control points are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the control points. For example,

animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword #all to animate all control points.

See also Class and Object Inspector Functions and Scripting Vertex and Control Point Animation for details on accessing the control points in an FFD and Modifier Sub-Object Transform Properties for details on the coordinate system used for FFD control points.

animateAll <FFD_2x2x2>

Applies controllers to all control points of the FFD modifier.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Class and Object Inspector Functions

Scripting Vertex and Control Point Animation

Modifier Sub-Object Transform Properties


FFD_3x3x3 : Modifier

Constructor

ffd_3x3x3 ...

Properties

<FFD_3x3x3>.dispLattice Boolean default: true -- alias: Lattice

Draws lines connecting the control points to make a grid.

<FFD_3x3x3>.dispSource Boolean default: false—alias: Source_Volume

Displays the control points and lattice in their unmodified state.

<FFD_3x3x3>.deformType Integer default: 0

Deform type:

0- Only In Volume (Deforms vertices that lie inside the source volume.)

1- All Vertices (Deforms all vertices, regardless of whether they lie inside or outside the source volume.)

<FFD_3x3x3>.inPoints Boolean default: true -- alias: Inside_Points

Only control points inside the object are affected by Conform to Shape.

<FFD_3x3x3>.outPoints Boolean default: true -- alias: Outside_Points

Only control points outside the object are affected by Conform to Shape.

<FFD_3x3x3>.offset Float default: 0.05 -- animatable

The distance by which control points affected by Conform to Shape are offset from the object surface.

<FFD_3x3x3>.lattice_transform SubAnim

<FFD_3x3x3.lattice_transform>.position Point3 default: [0,0,0] -- animatable

<FFD_3x3x3.lattice_transform>.rotation Quat default: (quat 0 0 0 1) -- animatable

<FFD_2x2x2.lattice_transform>.scale Point3 default: [1,1,1] -- animatable

Notes

The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4.

Methods

conformToShape <FFD_3x3x3>

conforms the control points of the FFD to the node the FFD is applied to. If an instance of the FFD modifier has been applied to more than one object, no action is performed.

resetLattice <FFDBox>

resets the control points of the FFD to their default positions.

animateVertex <FFD_3x3x3> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where <control_point_spec> is one of:

<integer_index>

<integer_index_array>

#all

By assigning controllers to the control points, the control points are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the control points. For example,

animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword #all to animate all control points.

See also Class and Object Inspector Functions and Scripting Vertex and Control Point Animation for details on accessing the control points in an FFD and Modifier Sub-Object Transform Properties for details on the coordinate system used for FFD control points.

animateAll <FFD_3x3x3>

Applies controllers to all control points of the FFD modifier.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Class and Object Inspector Functions

Scripting Vertex and Control Point Animation

Modifier Sub-Object Transform Properties


FFD_4x4x4 : Modifier

Constructor

ffd_4x4x4 ...

Properties

<FFD_4x4x4>.dispLattice Boolean default: true -- alias: Lattice

Draws lines connecting the control points to make a grid.

<FFD_4x4x4>.dispSource Boolean default: false—alias: Source_Volume

Displays the control points and lattice in their unmodified state.

<FFD_4x4x4>.deformType Integer default: 0

Deform type:

0- Only In Volume (Deforms vertices that lie inside the source volume.)

1- All Vertices (Deforms all vertices, regardless of whether they lie inside or outside the source volume.)

<FFD_4x4x4>.inPoints Boolean default: true -- alias: Inside_Points

Only control points inside the object are affected by Conform to Shape.

<FFD_4x4x4>.outPoints Boolean default: true -- alias: Outside_Points

Only control points outside the object are affected by Conform to Shape.

<FFD_4x4x4>.offset Float default: 0.05 -- animatable

The distance by which control points affected by Conform to Shape are offset from the object surface.

<FFD_4x4x4>.lattice_transform SubAnim

<FFD_4x4x4.lattice_transform>.position Point3 default: [0,0,0] -- animatable

<FFD_4x4x4.lattice_transform>.rotation Quat default: (quat 0 0 0 1) -- animatable

<FFD_4x4x4.lattice_transform>.scale Point3 default: [1,1,1] -- animatable

Notes

The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4.

Methods

conformToShape <FFD_4x4x4>

conforms the control points of the FFD to the node the FFD is applied to. If an instance of the FFD modifier has been applied to more than one object, no action is performed.

resetLattice <FFDBox>

resets the control points of the FFD to their default positions.

animateVertex <FFD_4x4x4> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where <control_point_spec> is one of:

<integer_index>

<integer_index_array>

#all

By assigning controllers to the control points, the control points are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the control points. For example,

animateVertex $box01.modifier[1] #all

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 and Scripting Vertex and Control Point Animation for details on accessing the control points in an FFD and Modifier Sub-Object Transform Properties for details on the coordinate system used for FFD control points.

animateAll <FFD_4x4x4>

Applies controllers to all control points of the FFD modifier.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Class and Object Inspector Functions

Scripting Vertex and Control Point Animation

Modifier Sub-Object Transform Properties


FFD_Select : Modifier

Constructor

ffd_select ...

Properties

There are no additional properties for FFD_Select.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Face_Extrude : Modifier

Constructor

face_extrude ...

Properties

<Face_Extrude>.amount Float default: 0.0 -- animatable

The extent of the extrusion.

<Face_Extrude>.scale Float default: 100.0 -- animatable

Scales each cluster of selected faces independently about its center.

<Face_Extrude>.extrude_center Point3 default: [0,0,0] -- animatable; alias: extrudeFromCenter

Extrudes each vertex radially from the point.

Notes

The Extrude From Center parameter is not accessible by MAXScript in 3ds max 4.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Fillet_Chamfer : Modifier

Constructor

fillet_chamfer ...

Properties

There are no additional properties for Fillet_Chamfer.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Flex : Modifier

Constructor

flex ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Flex>.flex Float default: 1.0 -- animatable

Sets the amount of flex and bend. Larger values increase the effect. Range=0 to 1000.

<Flex>.strength Float default: 3.0 -- animatable

Sets the spring strength. A value of 100 is rigid. Range=0 to 100.

<Flex>.sway Float default: 7.0 -- animatable

Sets the time for the object to come to rest. Lower values increase the time for the object to come to rest. Range=0 to 100.

<Flex>.chase Boolean default: true

Turns chase springs on/off.

<Flex>.center Boolean default: true

Turns the use of weights on/off.

<Flex>.solver Integer default: 0

The type of solver that will be used:

0- Euler Solver

1- Mid-point solver

2- Runnge Kutta

The higher the solver number, the more accurate/stable it is, and the slower it will run.

<Flex>.samples Integer default: 5 -- animatable

The number of samples per frame that the solver will use. The higher the number, the more accurate and stable; at the cost of a slower system.

<Flex>.stretch Float default: 5.0 -- animatable

This parameter slaves to the stretch strength/sway fields. It is normalized then copied to the strength/sway fields to prevent the system from becoming unstable.

<Flex>.stiffness Float default: 0.1 -- animatable

This parameter slaves to the torque strength/sway fields. It is normalized then copied to the strength/sway fields to prevent the system from becoming unstable.

<Flex>.paintStrength Float default: 0.1

Sets the amount of weight that the brush leaves on the mesh. Higher values leave more weight. Range=-1 to 1.

<Flex>.paintRadius Float default: 36.0

Set the size of the brush in world units. Range=.001 to 99999.

<Flex>.paintFeather Float default: 0.7

Set the hardness of the brush. A value of 1 is soft. Range=-1 to 1.

<Flex>.absolute Boolean default: false

Turn on to change the value of the Vertex Weight parameter to assign absolute weights to the selected vertices. Turn off to add or remove weight based on the vertices current weight.

<Flex>.forceNode ArrayParameter default: #() --array containing Force Nodes; alias: Force_Nodes

Assigns force effect to particle space warps identified in an array.

<Flex>.colliderNode ArrayParameter default: #() -- node array

Array contains a list of collider objects that flex will use.

<Flex>.referenceFrame Integer default: 0 -- alias: Reference_Frame

Flex will start computing at this frame.

<Flex>.endFrame Integer default: 100

Flex will stop computing after this time.

<Flex>.enableEndFrame Boolean default: false

Turns the end frame on/off.

<Flex>.affectAll Boolean default: false

Forces flex to ignore any selection in the stack, causing it to flex the entire object.

<Flex>.enableAdvanceSprings Boolean default: false

Enables the advance spring fields. When this is off, the Stretch and Torque parameters are slaved to the Stretch and Stiffness parameters.

<Flex>.stretchStrength Float default: 0.2 -- animatable

Controls the strength of stretch springs.

<Flex>.stretchSway Float default: 0.2 -- animatable

Controls the sway of stretch springs.

<Flex>.torqueStrength Float default: 0.2 -- animatable

Controls the strength of torque springs.

<Flex>.torqueSway Float default: 0.2 -- animatable

Controls the sway of torque springs.

<Flex>.holdLength Boolean default: false

Turns on/off the hold length parameter.

<Flex>.holdLengthPercent Float default: 25.0

The maximum percentage the spring can stretch/squash.

<Flex>.addMode Integer default: 0

Flag to determine how springs will be added:

0- Single spring across selected vertices

1- Edge Springs

2- Edge Springs across only selected vertices

3- Hold Springs

4- Hold Springs across only selected vertices

<Flex>.displaySprings Boolean default: false

Turns on/off the display of spring when in sub-object mode.

<Flex>.holdRadius Float default: 50.0

The maximum distance that will be looked around when the hold springs are added.

<Flex>.extraStrength ArrayParameter default: #(0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2) -- float array

Control the strength of extra springs (those that belong to a group other than 0 [stretch] or 1 [torque]).

<Flex>.extraSway ArrayParameter default: #(0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2) -- float array

Control the sway of extra springs (those that belong to a group other than 0 [stretch] or 1 [torque]).

<Flex>.lazyEval Boolean default: false

Turns on/off lazy evaluation, which causes the system to be reevaluated less at the expense of a less accurate display.

<Flex>.springColors ArrayParameter default: #([0,0,1], [0.909091,0,0], [0.818182,0,0], [0.727273,0,0], [0.636364,0,0], [0.545455,0,0], [0.454545,0,0], [0.363636,0,0], [0.272727,0,0], [0.181818,0,0], [0.0909091,0,0], [0,0,0]) -- point3 array

The colors for the springs for each group.

<Flex>.customSpringDisplay ArrayParameter default: #(true, true, true, true, true, true, true, true, true, true, true, true) -- bool array

This boolean array lets you turn on/off the display of the spring group.

<Flex>.createSpringDepth Integer default: 2

The number of times the system is recursed when using create soft body.

<Flex>.createSpringMult Float default: 2.0

The amount the flex effect is multiplied after each recursion when using create soft body.

The following property is defined by Flex, but is not used:

<Flex>.paintBackface Boolean default: true

Flex Methods

Paint <flex>

Presses the paint button in the flex interface.

SetReference <flex>

Presses the Set Reference button in the flex interface.

Reset <flex>

Presses the Reset button in the flex interface.

AddForce <flex> <force>

Adds a force to the force list.

force (node) - The force to be added to the force list.

RemoveForce <flex> <force>

Removes a force to the force list.

force (integer) - The index of the force to be removed. If this index = -1 then the selected force will be removed.

NumberVertices <flex>

Returns and integer containing the number of points in the system.

SelectVertices <flex> <sel> <update>

Selects the vertices passed in sel.

Sel (bitarray) - The bitarray that holds the selection.

Update (boolean) - Determines whether the viewports get updated.

GetSelectedVertices <flex>

Returns bitarray containing the current selected vertices.

GetVertexWeight <flex> <index>

Returns the weight of a specific vertex.

index (integer) - The index of the vertex you want to get the weight of.

SetVertexWeight <flex> <Index_tab> <values_tab>

Sets the weight of vertices. These tables should be the same size.

index_tab (integer table) - A table of indices of the vertex you want to set the weight of.

values_tab (float table) - A table of values containing the weights.

SetEdgeList <flex> <sel> <update>

Sets the edges to sel.

Sel (bitarray) - The bitarray that holds the edge selection.

Update (boolean) - Determines whether the viewports get updated.

GetEdgeList <flex>

Returns bitarray containing the current edge selection list.

AddSpringFromSelection <flex> <flag> <addDupes>

This creates one spring between 2 selected vertices that belong to a group.

flag (integer) - The group that this spring will belong to.

addDupes (boolean) - Will add duplicates if true.

addSpring <flex> <a> <b> <flag> <addDupes>

This creates a spring between the 2 specified vertices.

a (integer) - Index of vertex of the start of the spring.

b (integer) - Index of the vertex of the end of the spring.

flag (integer) - Group springs belongs to (0 to12).

addDupes (boolean) – When true, if there is a duplicate spring it will be added.

removeAllSprings <flex>

Removes all the springs the in the system.

addSpringButton <flex>

Equivalent of hitting the Add Spring button in the interface.

RemoveSpringButton <flex>

Equivalent of hitting the Remove Spring button in the interface.

optionsButton <flex>

Equivalent of hitting the Options button in the interface.

createSimpleSoftButton <flex>

Equivalent of hitting the Create Simple Soft Bodies button in the interface.

RemoveSpringByEnd <flex> <a>

This removes all springs that are connected to a vertex.

a (integer) – The vertex index to be checked.

removeSpringByEnds <flex> <a> <b>

This removes all springs that are connected to both vertex a and b.

a (integer) – First vertex index.

b (integer) – Second vertex index.

removeSpringByIndex <flex> <index>

Remove a spring from the list which is at index in the spring list.

index (integer) – Index of the spring.

numberSprings <flex>

Returns the number of springs in the system

getSpringGroup <flex> <index>

Returns the group that the spring belongs to.

index (integer) – Index of the spring you want to examine.

setSpringGroup <flex> <index> <group>

Sets the spring's groups.

index (integer) – Index of the spring.

group (integer) – The group number (0-12).

getSpringLength <flex> <index>

Gets the rest length of a particular spring.

index (integer) – Index of the spring that you want to examine.

setSpringLength <flex> <index> <length>

Sets the rest length of a particular spring.

index (integer) – Index of the spring that you want to examine.

length (float) – The rest length of the spring.

getIndex <flex> <a> <b>

Returns the index of a spring that uses vertex a and b.

a (integer) – Index of the start vertex of the spring.

b (integer) – Index of the start end of the spring.

FlexOps Methods

flexOps.GetNumberVertices <Flex>

Returns the number of vertices in the object the Flex modifier is applied to.

flexOps.GetVertexWeight <Flex> <vertex_index_integer>

Returns the weight of the specified vertex.

flexOps.SelectVertices <Flex> \

( <vertex_index_integer> | <index_integer_array> | <bitarray> )

Selects the specified vertices. Clears any previously selected vertices.

flexOps.isEdgeVertex <Flex> <vertex_index_integer>

Returns 0 if the specified vertex is not an edge vertex, 1 if it is an edge vertex.

flexOps.ClearEdgeVertices <Flex> \

( <vertex_index_integer> | <index_integer_array> )

Sets the specified vertices to not be edge vertices.

flexOps.SetEdgeVertices <Flex> \

( <vertex_index_integer> | <index_integer_array> )

Sets the specified vertices to be edge vertices.

flexOps.SetVertexWeights <Flex> \

( <vertex_index_integer> | <index_integer_array> ) \

( <weight_integer> | <weight_integer_array> )

Assigns the specified weights to the specified vertices. If the vertices and weights are specified as arrays, the arrays must be of equal size.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Lathe : Modifier

Constructor

lathe ...

Properties

<Lathe>.degrees Float default: 360.0 -- animatable, angle

Determines the number of degrees that the object is spun around the axis of revolution (0 to 360, default=360). You can set keyframes for Degrees to animate the circular growth of a lathed object. The Lathe axis auto-sizes itself to the height of the shape being lathed.

<Lathe>.weldCore Boolean default: false

When on, simplifies the mesh by welding together vertices that lie on the axis of revolution.

<Lathe>.flipNormals Boolean default: false

Depending on the direction of the vertices on your shape, and the direction of rotation, the lathed object might be inside out. Toggle this value to fix this.

<Lathe>.segs Integer default: 16 -- animatable, alias: segments

Determines how many interpolated segments are created in the surface between the start and endpoint.

<Lathe>.capStart Boolean default: false

Caps the start of the lathed object with Degrees set to less than 360 and a closed shape.

<Lathe>.capEnd Boolean default: false

Caps the end of the lathed object with Degrees set to less than 360 and a closed shape.

<Lathe>.capType Integer default: 0

Cap type:

0- 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.)

1- Grid (Arranges cap faces in a square grid trimmed at the shape boundaries. This method produces a surface of evenly sized faces that can easily be deformed by other modifiers.)

<Lathe>.output Integer default: 1

Output:

0- Patch (Produces an object that you can collapse to a patch object.)

1- Mesh (Produces an object that you can collapse to a mesh object.)

2- NURBS (Produces an object that can be collapsed to a NURBS surface.)

<Lathe>.mapCoords Boolean default: false

When on, applies mapping coordinates to the lathed object. When Degrees is less than 360, and Generate Mapping Coordinates is turned on, additional mapping coordinates are applied to the end caps, placing a 1 x 1 tile on each cap.

<Lathe>.matIDs Boolean default: true

When on, the software assigns different material IDs to the sides and the caps of the lathed object. Specifically, the sides receive ID 3, and the caps (when Degrees is less than 360 and the lathed shape is closed) receive IDs 1 and 2.

<Lathe>.useShapeIDs Boolean default: false

When on, the software uses the material ID values assigned to segments in the object.

<Lathe>.smooth Boolean default: true

When on, applies smoothing to the extruded shape.

<Lathe>.axis SubAnim

At this sub-object level, you can transform and animate the axis of revolution.

<Lathe.axis>.position Point3 default: [0,0,0] -- animatable

Position of the axis of revolution.

<Lathe.axis>.rotation Quat default: (quat -0.707107 0 0 0.707107) -- animatable

Rotation of the axis of revolution.

<Lathe.axis>.scale Point3 default: [1,1,1] -- animatable

Scale of the axis of revolution.

Notes

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

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Lattice : Modifier

Constructor

lattice ...

Properties

<Lattice>.Strut_Radius Float default: 2.0 -- animatable

The radius of the struts.

<Lattice>.Strut_Segments Integer default: 1 -- animatable

The number of segments along the struts. Increase this value when you need to deform or distort the struts with subsequent modifiers.

<Lattice>.Strut_Sides Integer default: 4 -- animatable

The number of sides around the perimeter of the struts.

<Lattice>.Joint_Radius Float default: 5.0 -- animatable

The radius of the joints.

<Lattice>.Joint_Segs Integer default: 1 -- animatable

The number of segments in the joints. The more segments, the more spherical the joints' shape.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Linked_XForm : Modifier

Constructor

linked_xform ...

Properties

<Linked_xform>.Control Node default: undefined

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

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


MaterialByElement : Modifier

Constructor

materialByElement ...

Properties

<MaterialByElement>.method Integer default: 1

Set method:

0- Random Distribution (Assigns the materials at random to different elements in the object.)

1- 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.

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

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


MaterialModifier : Modifier

Constructor

materialModifier ...

Properties

<Materialmodifier>.materialid Integer default: 1 -- animatable, alias: Material_ID

The material ID to be assigned. If the input object is in face sub-selection, then the ID is only applied to selected faces, otherwise it is applied to the entire object. The ID number refers to one of the materials in a multi/sub-object material.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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:

0- Ice (The default Solidity setting.)

1- Glass (Uses a high Solidity setting to simulate glass.)

2- Jelly (Causes a significant drooping effect in the center.)

3- Custom (Sets any solidity between 0.2 and 30.0.)

<Melt>.Solidity_Custom_Value Float default: 1.0 -- animatable

Custom solidity value.

<Melt>.axis Integer default: 0

The axis (local to the object) on which the melt will occur. Note that this axis is local to the Melt gizmo and not related to the selected entity.

0- Z

1- Y

2- 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.

0- Don't Flip Axis

1- 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.

<Melt.gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the gizmo. Rotating the gizmo takes place with respect to its center.

<Melt.gizmo>.scale Point3 default: [1,1,1] -- animatable

The scaling of the gizmo. Scaling the gizmo takes place with respect to its center.

The following properties are defined by Melt, but are not used:

<Melt>.cut_Off__obsolete Float default: 0.0 -- animatable

<Melt>.Confine_To_Gizmo Integer default: 0

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


MeshSmooth : Modifier

Constructor

meshSmooth ...

Properties

<MeshSmooth>.subdivMethod Integer default: 2

Selects the Subdivision method to use:

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

<MeshSmooth>.smoothness Float default: 1.0 -- animatable; alias: smoothness_filter

Determines how sharp a corner must be before faces are added to smooth it. Smoothness is calculated as the average angle of all edges connected to a vertex. A value of 0.0 prevents the creation of any faces. A value of 1.0 adds faces to all vertices even if they lie on a plane.

<MeshSmooth>.useRenderIterations Boolean default: false; alias: use_render_iterations

Turn on/off use of render iterations, for using a different number of iterations at render time. When off, the software will use the iterations value.

<MeshSmooth>.renderIterations Integer default: 0 -- animatable; alias: render_iterations

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

<MeshSmooth>.useRenderSmoothness Boolean default: false; alias: use_render_smoothness

Turn on/off use of render smoothness, for using a different smoothness value at render time. When off, the software will use the smoothness value.

<MeshSmooth>.renderSmoothness Float default: 1.0 -- animatable; alias: render_smoothness

Lets you choose a different Smoothness value to be applied to the object at render time.

<MeshSmooth>.ignoreBackfacing Boolean default: false

When on, selection of sub-objects selects only those sub-objects whose normals are visible in the viewport. When off (the default), selection includes all sub-objects, regardless of the direction of their normals.

<MeshSmooth>.controlLevel Integer default: 0

Allows you to see the control mesh after one or more iterations and to edit sub-object points and edges at that level.

<MeshSmooth>.displayCage Boolean default: false; alias: display_control_mesh

Displays an orange wireframe gizmo that shows what the control mesh looks like after it's been converted to polygons (if applicable) and before the smoothing occurs.

<MeshSmooth>.useSoftSel Boolean default: false

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

<MeshSmooth>.useEdgeDist Boolean default: false

Turn on/off use Edge Distance.

<MeshSmooth>.edgeDist Integer default: 1

Limits the region affected by the number of edges between the selection and the affected vertices.

<MeshSmooth>.affectBackfacing Boolean default: false

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which they're attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence.

<MeshSmooth>.falloff Float default: 20.0

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry.

<MeshSmooth>.pinch Float default: 0.0

Raises and lowers the top point of the curve along the vertical axis. Sets the relative "pointedness" of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis.

<MeshSmooth>.bubble Float default: 0.0

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

<MeshSmooth>.strength Float default: 0.5 -- animatable

Sets the size of the added faces using a range from 0.0 to 1.0.

Values near 0.0 create small faces that are very thin and close to the original vertices and edges, values near 0.5 size faces evenly between edges, and values near 1.0 create large new faces and make the original faces very small.

<MeshSmooth>.Relax Float default: 0.0 -- animatable

Applies a positive relax effect to smooth all vertices.

<MeshSmooth>.limitSurface Boolean default: false; alias: project_to_limit_surface

Places all points on the "limit surface" of the MeshSmooth result, which is the surface you'd get after an infinite number of iterations.

<MeshSmooth>.smoothResult Boolean default: false; alias: smooth_output

Applies the same smoothing group to all faces.

<MeshSmooth>.sepByMats Boolean default: false; alias: separate_by_materials

Prevents the creation of new faces for edges between faces that do not share Material IDs.

<MeshSmooth>.sepBySmGroups Boolean default: false; alias: separate_by_smoothing_group

Prevents the creation of new faces at edges between faces that don't share at least one smoothing group.

<MeshSmooth>.faceType Integer default: 1

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.

<MeshSmooth>.keepConvex Boolean default: false; alias: keep_input_faces_convex

Keeps all input polygons convex. Selecting this option causes non-convex polygons to be handled as a minimum number of separate faces, each of which is convex.

<MeshSmooth>.update Integer default: 0; alias: update_options

Set update options:

0- Always update

1- Update when rendering

2- Update Manually

<MeshSmooth>.reset Integer default: 0

Select reset settings:

0- Reset all levels

1- Reset this level

Notes

The edge and vertex weight properties are not accessible to MAXScript in 3ds max 4.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Mesh_Select : Modifier

Constructor

mesh_select ...

Properties

<Mesh_Select>.Use_Soft_Selection Integer default: 0 -- animatable

Use_Soft_Selection = 0 - off; 1 - on

<Mesh_Select>.falloff Float default: 20.0 -- animatable

<Mesh_Select>.Pinch Float default: 0.0 -- animatable

<Mesh_Select>.Bubble Float default: 0.0 -- animatable

See the getVertSelection(), getFaceSelection(), and getEdgeSelection() functions in Editable_Mesh for information about accessing the current selections in the Mesh_Select modifier.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Mirror : Modifier

Constructor

mirror ...

Properties

<Mirror>.mirror_axis Integer default: 0

The axis or axes about which the mirroring takes place:

0- X

1- Y

2- Z

3- XY

4- YZ

5- ZX

<Mirror>.Mirror_Offset Float default: 0.0 -- animatable

The offset, in units, from the mirror axis.

<Mirror>.copy Boolean default: false

When on, copies the geometry rather than simply mirroring it.

<Mirror>.mirror_center SubAnim

Represents the axis of the mirror effect. You can move, rotate or scale the gizmo to affect the mirroring.

<Mirror.Mirror_Center>.position Point3 default: [0,0,0] -- animatable

The position of the mirror center.

<Mirror.Mirror_Center>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the mirror center.

<Mirror.Mirror_Center>.scale Point3 default: [1,1,1] -- animatable

The scaling of the mirror center.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Morpher : Modifier

Constructor

Morpher ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Morpher>.Use_Limits Integer default: 1

When on, 3ds max uses the minimum and maximum limits for all channels.

<Morpher>.Spinner_Minimum Float default: 0.0

The minimum limit.

<Morpher>.Spinner_Maximum Float default: 100.0

The maximum limit.

<Morpher>.Use_Selection Integer default: 0

Turn on to limit morphing to vertices selected in a modifier below the Morpher modifier in the modifier stack.

<Morpher>.Value_Increments Integer default: 1

<Morpher>.Autoload_of_targets Integer default: 0

Turn this on to allow animated targets to be updated dynamically by the Morpher modifier.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


NCurve_Sel : Modifier

Constructor

NCurve_Sel ...

Properties

There are no additional properties for NCurve_Sel.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


NoiseModifier : Modifier

Constructor

noiseModifier ...

Properties

<Noisemodifier>.seed Integer default: 0 -- animatable

A random start point is generated from the number you set.

<Noisemodifier>.scale Float default: 100.0 -- animatable

The size of the noise effect (not strength). Larger values produce smoother noise, lower values more jagged noise.

<Noisemodifier>.fractal Boolean default: false -- animatable

When on, produces a fractal effect based on current settings.

<Noisemodifier>.roughness Float default: 0.0 -- animatable, alias: rough

The extent of fractal variation. Lower values are less rough than higher values.

<Noisemodifier>.iterations Float default: 6.0 -- animatable

The number of iterations (or octaves) used by the fractal function. Fewer iterations use less fractal energy and generate a smoother effect. An iteration of 1.0 is the same as turning .fractal off.

<Noisemodifier>.strength Point3 default: [0,0,0] -- animatable

The strength of the noise effect along each of three axes. Enter a value for at least one of these axes to produce a noise effect.

<Noisemodifier>.animate Boolean default: false

Enables/disables animation playback.

<Noisemodifier>.frequency Float default: 0.25

The speed of the noise effect. Higher frequencies make the noise quiver faster. Lower frequencies produce a smoother and more gentle noise.

<Noisemodifier>.phase Time default: 0f -- animatable

Shifts the start and end points of the underlying wave.

<Noisemodifier>.center Point3 default: [0,0,0] -- animatable

You can move, rotate, or scale the center sub-object to affect the noise. You can also animate the sub-object transforms.

<Noisemodifier>.gizmo SubAnim

You can move, rotate, or scale the gizmo sub-object to affect the noise. You can also animate the sub-object transforms.

<Noisemodifier.gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the gizmo.

<Noisemodifier.gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the gizmo.

<Noisemodifier.gizmo>.scale Point3 default: [1,1,1] -- animatable

The scaling of the gizmo.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


NormalModifier : Modifier

Constructor

normalModifier ...

Properties

<Normalmodifier>.unify Boolean default: false

When on, unifies the normals of an object by flipping the normals so that they all point in the same direction, usually outward.

<Normalmodifier>.flip Boolean default: false

When on, reverses the direction of all the surface normals of the faces of the selected object or objects.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


NSurf_Sel : Modifier

Constructor

NSurf_Sel ...

Properties

There are no additional properties for NSurf_Sel.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Optimize : Modifier

Constructor

optimize ...

Properties

<optimize>.renderLOD Integer default: 0

You can store two different optimization settings for the renderer, in two separate levels; L1 & L2. Set the level of display for the default scanline renderer:

0- L1

1- L2

<optimize>.viewLOD Integer default: 0

You can store two different optimization settings for the viewport, in two separate levels; L1 & L2. Set the level of display for the viewport:

0- L1

1- L2

<optimize>.facethreshold1 Float default: 4.0 -- animatable, angle, alias: Face_Threshold_L1

The threshold angle used to determine which faces are collapsed. Low values produce less optimization but better approximations of the original shape. Higher values improve optimization, but are more likely to result in faces that render poorly.

<optimize>.edgethreshold1 Float default: 1.0 -- animatable, angle, alias: Edge_Threshold_L1

Sets a different threshold angle for open edges (those that bound only one face). A low value preserves open edges. At the same time you can apply a high face threshold to get good optimization.

<optimize>.bias1 Float default: 0.1 -- animatable, alias: Bias_L1

Helps eliminate the skinny or degenerate triangles that occur during optimization, which can cause rendering artifacts. Higher values keeps triangles from becoming degenerate. The default of 0.1 is enough to eliminate the skinniest triangles.

<optimize>.Max_Edge_Length_1 Float default: 0.0 -- animatable

The maximum length, beyond which an edge cannot be stretched when optimized. When Max_Edge_Length_1 is 0, it has no effect. Any value greater than 0 specifies the maximum length of the edges.

<optimize>.preservemat1 Boolean default: false

When on, prevents face collapse across material boundaries.

<optimize>.preservesmooth1 Boolean default: false

When turned on, allows only faces that share at least one smoothing group to collapse.

<optimize>.facethreshold2 Float default: 4.0 -- animatable, angle, alias: Face_Threshold_L2

The threshold angle used to determine which faces are collapsed. Low values produce less optimization but better approximations of the original shape. Higher values improve optimization, but are more likely to result in faces that render poorly.

<optimize>.edgethreshold2 Float default: 1.0 -- animatable, angle, alias: Edge_Threshold_L2

Sets a different threshold angle for open edges (those that bound only one face). A low value preserves open edges. At the same time you can apply a high face threshold to get good optimization.

<optimize>.bias2 Float default: 0.1 -- animatable, alias: Bias_L2

Helps eliminate the skinny or degenerate triangles that occur during optimization, which can cause rendering artifacts. Higher values keeps triangles from becoming degenerate. The default of 0.1 is enough to eliminate the skinniest triangles.

<optimize>.Max_Edge_Length_2 Float default: 0.0 -- animatable

The maximum length, beyond which an edge cannot be stretched when optimized. When Max_Edge_Length_2 is 0, it has no effect. Any value greater than 0 specifies the maximum length of the edges.

<optimize>.preservemat2 Boolean default: false

When on, prevents face collapse across material boundaries.

<optimize>.preservesmooth2 Boolean default: false

When turned on, allows only faces that share at least one smoothing group to collapse.

<optimize>.manualUpdate Boolean default: false

When on, enables the Update button. When turned off, Optimize works as it does by default, updating the viewport display dynamically.

<optimize>.autoedge Boolean default: false

When on, turns edges on and off following optimization. Turns on any open edges. Turns off any edges between faces whose normals are within the face threshold; such edges beyond the threshold are not turned on.

Notes

The Manual Update property is not accessible to MAXScript in 3ds max 4.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


PatchDeform : Modifier

Constructor

patchDeform ...

Properties

<PatchDeform>.U_Percent Float default: 50.0 -- animatable, percentage

Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage of the U distance. This defaults to a setting of 50 percent, which places the object at the center of the gizmo patch. A setting of 0 percent places the object at the left edge of the gizmo patch, as seen from the viewport where the patch was created.

<PatchDeform>.U_Stretch Float default: 1.0 -- animatable

Scales the object along the U (horizontal) axis of the gizmo patch.

<PatchDeform>.V_Percent Float default: 50.0 -- animatable, percentage

Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.

<PatchDeform>.V_Stretch Float default: 1.0 -- animatable

Scales the object along the V (vertical) axis of the gizmo patch.

<PatchDeform>.rotation Float default: 0.0 -- animatable, angle

Rotates the modified object with respect to the gizmo patch.

<PatchDeform>.Plane_to_Patch_Deform Integer default: 0

Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch:

0- XY

1- YZ

2- ZX

<PatchDeform>.Flip_deformation_axis Integer default: 0

When on, reverses the gizmo direction.

0- Don't flip

1- 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.

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

Notes

There is no way to specify the patch to deform to using MAXScript in 3ds max 4.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


PathDeform : Modifier

Constructor

pathDeform ...

Properties

<PathDeform>.path Node default: undefined

The selected path object.

<PathDeform>.Percent_along_path Float default: 0.0 -- animatable, percentage

Moves the object along the gizmo path based on a percentage of the path length.

<PathDeform>.Stretch Float default: 1.0 -- animatable

Scales the object along the gizmo path, using the object's pivot point as the base of the scale.

<PathDeform>.rotation Float default: 0.0 -- animatable, angle

Rotates the object about the gizmo path.

<PathDeform>.Twist Float default: 0.0 -- animatable, angle

Twists the object about the path. The twist angle is based on the rotation of one end of the overall length of the path. Typically, the deformed object takes up only a portion of the path, so the effect can be subtle.

<PathDeform>.axis Integer default: 2

The axus if the gizmo object which is aligned with the corresponding local axis of the path object:

0- X

1- Y

2- Z

<PathDeform>.Flip_deformation_axis Integer default: 0

When on, reverses the gizmo path 180 degrees about the specified axis.

0- Don't flip

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

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Preserve : Modifier

Constructor

preserve ...

Properties

<Preserve>.iterations Integer default: 25 -- animatable

The number of calculations toward the solution. The higher this number, the closer the object comes to matching the original object and the slower the process. When this is set to zero, the original object has no effect, as if the Preserve modifier were never applied.

<Preserve>.Edge_Length_Weight Float default: 1.0 -- animatable

The relative importance of the edge length.

<Preserve>.Face_Angle_Weight Float default: 0.3 -- animatable

The relative importance of the face angle.

<Preserve>.Volume_Weight Float default: 0.3 -- animatable

The relative importance of the volume.

<Preserve>.Apply_To_Whole_Mesh Integer default: 0

When on, applies Preserve to the entire object, regardless of the selection passed from previous levels of the stack:

0- Off

1- On

<Preserve>.Selected_Verts_Only Integer default: 0

When on, uses previous sub-object vertex selections. Note that it doesn't matter if the Vertex sub-object level is active in a previous stack item. As long as vertices have been selected, Preserve will use that selection.

0- Off

1- On

<Preserve>.Invert_Selection Integer default: 0

When on, inverts the selection passed up the stack.

0- Off

1- On

Notes

There is no way to specify the "Original" object using MAXScript in 3ds max 4.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Push : Modifier

Constructor

push ...

Properties

<Push>.Push_Value Float default: 0.0 -- animatable

The distance in world units by which vertices are moved with respect to the object center. Use a positive value to move vertices outward, or a negative value to move vertices inward.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Relax : Modifier

Constructor

relax ...

Properties

<Relax>.iterations Integer default: 1 -- animatable

The number of times Relax is repeated. Each iteration recalculates average vertex locations based on the result of the previous iteration.

<Relax>.Relax_Value Float default: 0.5 -- animatable

The distance a vertex moves as a percentage of the distance between a vertex and the average location of its neighbors.

<Relax>.Keep_Boundary_Pts_Fixed Integer default: 1

When on, vertices at the edge of open meshes do not relax.

0- Off

1- On

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Ripple : Modifier

Constructor

ripple ...

Properties

<Ripple>.amplitude1 Float default: 5.0 -- animatable, alias: Amplitude_1

The amplitude of the first ripple.

<Ripple>.amplitude2 Float default: 5.0 -- animatable, alias: Amplitude_2

The amplitude of the second ripple, which is perpendicular to the first ripple.

<Ripple>.wavelength Float default: 25.0 -- animatable, alias: Wave_Length

The distance between the peaks of the wave. The greater the length, the smoother and more shallow the ripple for a given amplitude.

<Ripple>.phase Float default: 0.0 -- animatable

Shifts the ripple pattern over the object. Positive numbers move the pattern inward, while negative numbers move it outward.

<Ripple>.decay Float default: 0.0 -- animatable

Limits the effect of the wave generated from its center. A default decay of zero means that the wave will generate infinitely from its center. Increasing the decay value reduces the distance over which the wave is generated.

<Ripple>.center Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center of the ripple effect, and thus the shape and positions of the ripples.

<Ripple>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Ripple modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.

<Ripple.gizmo>.position Point3 default: [0,0,0] -- animatable

The poosition of the ripple gizmo.

<Ripple.gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the ripple gizmo.

<Ripple.gizmo>.scale Point3 default: [1,1,1] -- animatable

The scale of the ripple gizmo.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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.

<Skew>.axis Integer default: 2

The axis that will be skewed:

0- X

1- Y

2- Z

<Skew>.limit Boolean default: false

When on, applies limit constraints to the Skew modifier.

<Skew>.upperlimit Float default: 0.0 -- animatable, alias: Upper_Limit

The upper limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry.

<Skew>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit

The lower limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry.

<Skew>.center Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center of the Skew effect.

<Skew>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Skew modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.

<Skew.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the skew gizmo.

<Skew.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the skew gizmo.

<Skew.Gizmo>.scale Point3 default: [1,1,1] -- animatable

The scale of the skew gizmo.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Skin : Modifier

Constructor

skin ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Skin>.Effect Float default: 0.0

Absolute weight of selected vertices.

<Skin>.filter_vertices Boolean default: false

Turn vertex selection on/off.

<Skin>.filter_cross_sections Boolean default: true

Turn cross-section selection on/off.

<Skin>.filter_envelopes Boolean default: true

Turn envelope selection on/off.

<Skin>.draw_all_envelopes Boolean default: false

When turned on, displays all envelopes. When off, only the selected envelopes are displayed.

<Skin>.draw_vertices Boolean default: true

Turn on/off the display of weighted vertices.

<Skin>.ref_frame Integer default: 0

Sets the frame where the bones and the mesh are in a reference position.

<Skin>.paint_radius Float default: 24.0

Sets the brush radius.

<Skin>.paint_feather Float default: 0.7

Sets the brush falloff.

<Skin>.cross_radius Float default: 10.0

Scales the selected envelope cross-section.

<Skin>.always_deform Boolean default: true

Always deforms the skin when the bones are moved. The Animate button does not have to be turned on to move bones and deform the skin.

<Skin>.paint_str Float default: 0.1

Sets the brush strength.

<Skin>.localSquash Array default: #() -- float array

Amount of squash applied to each bone.

<Skin>.initialSquash Array default: #() -- float array

Array containing initial squash values for a bone.

<Skin>.initialStaticEnvelope Boolean default: false

When turned on, an initial static envelope size is used when a bone is added. When off, the initial envelope size is determined by the object bounding box.

<Skin>.initialInnerEnvelopePercent Float default: 0.75

The multiplier used to find the inner cross-section size when initialStaticEnvelope is false.

<Skin>.initialOuterEnvelopePercent Float default: 3.5

The multiplier used to find the outer cross-section size when initialStaticEnvelope is false.

<Skin>.initialEnvelopeInner Float default: 10.0

The inner cross-section size when initialStaticEnvelope is true.

<Skin>.initialEnvelopeOuter Float default: 50.0

The outer cross-section size when initialStaticEnvelope is true.

<Skin>.draw_all_gizmos Boolean default: true

Turn on/off the display off all gizmos.

<Skin>.draw_all_vertices Boolean default: false

Turns on/off the display of all vertices as small dots.

<Skin>.shadeweights Boolean default: true

Turn on/off display of weighted vertices using vertex colors.

<Skin>.envelopesAlwaysOnTop Boolean default: true

Turn on/off display of envelopes on top of the mesh.

<Skin>.crossSectionsAlwaysOnTop Boolean default: true

Turn on/off display of cross-sections on top of the mesh.

<Skin>.rigid_vertices Boolean default: false

When turned on, a single vertex can only be affected by one bone.

<Skin>.rigid_handles Boolean default: false

When turned on, all handles have the same weights as the knot that owns them.

<Skin>.fast_update Boolean default: false

When turned on, the system uses only rigid vertices for the viewport display.

<Skin>.gizmos Array default: #() -- max object array

Array containing all gizmos assigned to skin.

Methods

The following methods require that the Skin modifier be the displayed modifier in the Modify panel, and that the Modify panel is active.

skinops.addbone <Skin> <Bone_node> <Update_integer>

Adds a bone to the current system.

For Update_integer, - 1 forces a complete update and redraw, 0 does not update the system. This allows you to add a bunch of bones to a system and then update once at the end.

skinops.addBoneFromViewEnd <Skin>

Ends the addBoneFromViewStart command mode.

skinops.addBoneFromViewStart <Skin>

Puts you in a command mode where you can select bones from the viewport by clicking on them. You can exit this mode by right clicking or calling addBoneFromViewEnd.

skinops.addCrossSection <Skin> <BoneID_integer> <U_float> <InnerRadius_float> <OuterRadius_float>

Adds a cross section to the bone whose index matches BoneID_integer. U_float, which ranges from 0.0-1.0, defines where along the bone to add the cross-section.

skinops.addCrossSection <Skin> <U_float>

Adds a cross section to the current selected bone. The inner and outer radii are computed based on the neighboring cross sections. U_float, which ranges from 0.0-1.0, defines where along the bone to add the cross-section.

skinops.addCrossSection <Skin> <U_float> <InnerRadius_float> <OuterRadius_float>

Adds a cross section to the current selected bone. U_float, which ranges from 0.0-1.0, defines where along the bone to add the cross-section.

skinops.buttonAdd <Skin>

Presses the add bone button.

skinops.buttonAddCrossSection <Skin>

Presses the add cross section button.

skinops.buttonAddGizmo <Skin>

Presses the add gizmo button in the gizmo rollout.

skinops.buttonCopyGizmo <Skin>

Presses the copy gizmo button in the gizmo rollout.

skinops.buttonExclude <Skin>

Presses the exclude vertices button.

skinops.buttonInclude <Skin>

Presses the include vertices button.

skinops.buttonPaint <Skin>

Presses the paint button.

skinops.buttonPasteGizmo <Skin>

Presses the paste gizmo button in the gizmo rollout.

skinops.buttonRemove <Skin>

Presses the remove bone button.

skinops.buttonRemoveCrossSection <Skin>

Presses the remove cross section button.

skinops.buttonRemoveGizmo <Skin>

Presses the remove gizmo button in the gizmo rollout.

skinops.buttonSelectExcluded <Skin>

Presses the select excluded vertices button.

skinops.copySelectedBone <Skin>

Copies current selected bone properties to the copy buffer.

skinops.enableGizmo <Skin> <GizmoID_integer> <Enable_bool>

Enables/disables the gizmo type whose index equals GizmoID_integer.

skinOps.GetBoneName <Skin> <bone_integer> <nameflag_index>

Returns the name of the indexed bone as a string. where nameflag_index can be 0 or 1. If nameflag_index = 0 the node that holds the transform for this bone is returned; = 1 the name that exists in the list box is returned. If a Bones system is used for the Skin bones, the transform for a bone is held by its parent.

skinops.getBonePropEnvelopeVisible <Skin> <BoneID_integer>

Returns the bone visibility parameter of the bone. 0 is invisible, 1 is visible.

skinops.getBonePropFalloff <Skin> <BoneID_integer>

Returns the falloff parameter of the bone.

1 – linear

2 – sinual

3 – fast out

4 – slow out

skinops.getBonePropRelative <Skin> <BoneID_integer>

Gets the relative property of the bone. It returns 1 if relative or 0 is absolute.

skinops.GetCrossSectionU <Skin> <BoneID_integer> <CrossSectionID_integer>

Gets the U value from the specified bone and cross section

skinops.getCurrentSelectGizmoType <Skin>

Returns the current selected gizmo type.

skinops.GetEndPoint <Skin> <BoneID_integer>

Returns a point3 which is the end point of the bone.

skinOps.GetInnerRadius <Skin> \

<bone_integer> <CrossSectionID_integer>

Returns the inner cross section radius for the specified bone and cross section.

skinOps.GetNumberBones <Skin>

Returns the number of bones in the system.

skinOps.getNumberCrossSections <Skin> <bone_integer>

Returns the number of cross sections for the specified bone.

skinops.getNumberOfGizmos <Skin>

Returns the number of gizmos.

skinops.getNumberOfGizmoTypes <Skin>

Returns the number of gizmo types.

skinOps.GetNumberVertices <Skin>

Returns the number of vertices for the object the Skin modifier is applied to.

skinOps.GetOuterRadius <Skin> \

<bone_integer> <CrossSectionID_integer>

Returns the outer cross section radius for the specified bone and cross section.

skinOps.GetSelectedBone <Skin>

Returns the index of the current selected bone in the Bone list.

skinops.getSelectedBonePropEnvelopeVisible <Skin>

Returns the bone visibility parameter of the current selected bone. 0 is invisible, 1 is visible.

skinops.getSelectedBonePropFalloff <Skin>

Returns the falloff parameter of the current selected bone:

1 – linear

2 – sinual

3 – fast out

4 – slow out

skinops.getSelectedBonePropRelative <Skin>

Gets the relative property of the current selected bone. It returns 1 if relative or 0 is absolute.

skinops.getSelectedGizmo <Skin>

Returns the current selected gizmo.

skinops.GetStartPoint <Skin> <BoneID_integer>

Returns a point3 which is the start point of the bone.

skinOps.GetVertexWeight <Skin> \

<vertex_integer> <vertex_bone_integer>

Returns the influence of the Nth bone affecting the specified vertex.

skinOps.GetVertexWeightBoneID <Skin> \

<vertex_integer> <vertex_bone_integer>

Returns the system bone index of the Nth bone affecting the specified vertex.

skinOps.GetVertexWeightCount <Skin> <vertex_integer>

Returns the number of bones influencing the specified vertex.

skinops.isBoneSelected <Skin> <BoneID_integer>

Returns 1 if the bone is selected otherwise 0.

skinOps.IsVertexModified <Skin> <vertex_integer>

Returns 1 if the vertex has been modified, 0 if it has not been modified. A modified vertex is vertex that has been weighted by hand or painting, an unmodified vertex weight depends solely on the envelopes.

skinOps.IsVertexSelected <Skin> <vertex_integer>

Returns 1 if the vertex is selected, 0 if it is not selected.

skinops.loadEnvelope <Skin>

Opens the load envelopes dialog

skinops.loadEnvelope <Skin> <filename_string>

Loads the envelopes to the file supplied

skinops.multiRemove <Skin>

Brings up a list box where the user can delete multiple bones instead of one at a time.

skinops.pasteToAllBones <Skin>

Pastes the copy buffer to all the bones.

skinops.pasteToBone <Skin> <BoneID_int>

Pastes the copy buffer to bone id supplied.

skinops.pasteToSelectedBone <Skin>

Pastes the copy buffer to the current selected bone.

skinops.removebone <Skin>

Removes the current selected bone from the bones system.

skinops.removebone <Skin> <BoneID_integer>

Removes the BoneID from the bones system.

skinops.RemoveCrossSection $<Skin>

Removes the current selected cross section from the current selected bone.

skinops.RemoveCrossSection <Skin> <BoneID_integer> <CrossSectionID_integer>

Removes a particular cross-section from a particular bone.

skinOps.ReplaceVertexWeights <Skin> <vertex_integer> \

( <vertex_bone_integer> | <vertex_bone_array> ) \

( <weight_float> | <weight_array> )

Sets the influence of the specified bone(s) to the specified vertex. Any influence weights for the bone(s) that are not specified are erased. If the bones and weights are specified as arrays, the arrays must be of the same size.

skinops.resetAllBones <Skin>

Resets all bones.

skinops.resetSelectedBone <Skin>

Resets the current selected bone.

skinops.resetSelectedVerts <Skin>

Resets the current selected vertices.

skinops.saveEnvelope <Skin>

Opens the save envelopes dialog

skinops.saveEnvelope <Skin> <filename_string>

Saves the envelopes to the file supplied

skinOps.SelectBone <Skin> <bone_integer>

Selects the specified bone in the Bone list.

skinops.selectCrossSection <Skin> <CrossSectionID_integer> <Inner_Outer_integer>

Selects a cross section on the current selected bone.

For Inner_Outer_integer, 0 is the inner envelope 1 is the outer envelope.

skinops.selectEndPoint <Skin>

Selects the start point of the envelope the current selected bone.

skinops.selectGizmo <Skin> <gizmoID_int>

Desc – this function selects the gizmo who index equals gizmoID.

skinops.selectGizmoType <Skin> <gizmoTypeID_int>

Selects the gizmo type whose index equals gizmoTypeID.

skinops.selectNextBone <Skin>

Selects the next bone in the bone list.

skinops.selectPreviousBone <Skin>

Selects the next bone in the bone list.

skinops.selectStartPoint <Skin>

Selects the end point of the envelope of the current selected bone.

skinOps.SelectVertices <Skin> \

( <vertex_integer> | <vertex_array > | <<vertex_bitarray> )

Selects the specified vertices.

skinops.setBonePropEnvelopeVisible <Skin> <BoneID_integer> <Visible_integer>

Sets the bone visibility parameter of the bone whose index matches BoneID_integer.

For Visible_integer, 0 is visible, 1 is invisible when not selected.

skinops.setBonePropFalloff <Skin> <BoneID_integer> <Falloff_integer>

Sets the falloff parameter of the bone.

For Faloff_integer, the fall off of the bone is:

1 – linear

2 – sinual

3 – fast out

4 – slow out

skinops.setBonePropRelative <Skin> <BoneID_integer> <Relative_integer>

Sets the relative property of the bone whose index matches BoneID_integer.

For Relative_integer, 0 is absolute and 1 is relative.

skinops.SetCrossSectionU <Skin> <BoneID_integer> <CrossSectionID_integer> <U_float>

Sets the U value from the specified bone and cross section.

skinops.SetEndPoint <Skin> <BoneID_integer> <EndPointPos_point3>

Sets the end point of the specified bone.

skinOps.SetInnerRadius <Skin> \

<bone_integer> <CrossSectionID_integer> <Radius_float>

Sets the inner cross section radius for the specified bone and cross section.

skinOps.SetOuterRadius <Skin> \

<bone_integer> <CrossSectionID_integer> <Radius_float>

Sets the outer cross section radius for the specified bone and cross section.

skinops.setSelectedBonePropEnvelopeVisible <Skin> <Visible_integer>

Sets the bone visibility parameter of the current selected bone.

For Visible_integer, 0 = visible, 1 = invisible when not selected

skinops.setSelectedBonePropFalloff <Skin> <Falloff_integer>

Sets the falloff parameter of the current selected bone.

The falloff_integer sets the fall off of the bone:

1 – linear

2 – sinual

3 – fast out

4 – slow out

skinops.setSelectedBonePropRelative <Skin> <Relative_integer>

Sets the relative property of the current selected bone.

For relative_integer, 0 is relative mode, 1 is absolute mode.

skinops.SetStartPoint <Skin> <BoneID_integer> <EndPointPos_point3>

Sets the start point of the specified bone

skinOps.SetVertexWeights <Skin> <vertex_integer> \

( <vertex_bone_integer> | <vertex_bone_array> ) \

( <weight_float> | <weight_array> )

Sets the influence of the specified bone(s) to the specified vertex. Any influence weights for the bone(s) that are not specified are retained. If the bones and weights are specified as arrays, the arrays must be of the same size.

skinops.ZoomToBone <Skin> <All_boolean>

Zooms the active or all views to the selected bone. If All_boolean is true, then all views are zoomed.

skinops.ZoomToGizmo <Skin> <All_boolean>

Zooms the active or all views to the selected gizmo. If All_boolean is true, then all views are zoomed.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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:

0- 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.)

1- 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.)

2- Remove Top (Deletes all the faces and vertices above the Slice Plane.)

3- 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:

0- Operate on Face (Treats the selection set as a set of triangular faces, slicing each one in turn.)

1- Operate on Polygon (Treats the selection set as polygonal facets based on visible edges. Hidden edges within a polygon are recomputed to give the best result for the whole polygons.)

<sliceModifier>.slice_plane SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object to determine where the slice occurs. Scaling the gizmo has no effect, because its extents are effectively infinite. If you need to limit the extent of the slice, use it on a sub-object selection set of faces, rather than on the entire object.

<sliceModifier.Slice_Plane>.position Point3 default: [0,0,0] -- animatable

The position of the slice plane object.

<sliceModifier.Slice_Plane>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the slice plane object.

<sliceModifier.Slice_Plane>.scale Point3 default: [1,1,1] -- animatable

The scale of the slice plane object.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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.

Notes

See Editable_Mesh, Face Methods for a description of the smoothing group integer value

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SplineSelect : Modifier

Constructor

splineSelect ...

Properties

There are no additional properties for SplineSelect.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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.

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

0- Off

1- On

<Squeeze>.Squeeze_Lower_Limit Float default: -50.0 -- animatable

The limit of the squeeze effect in the positive direction along the Z axis.

<Squeeze>.Squeeze_Upper_Limit Float default: 50.0 -- animatable

The limit of the squeeze effect in the negative direction along the Z axis.

<Squeeze>.Bias Float default: 0.0 -- animatable, percentage

The relative amounts of bulge and squeeze while retaining a constant object volume.

<Squeeze>.Volume Float default: 100.0 -- animatable, percentage

Increases or decreases the effects of both Squeeze and Bulge in parallel.

<Squeeze>.center Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center, altering the Squeeze gizmo's shape, and thus the shape of the squeezed object.

<Squeeze>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Squeeze modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.

<Squeeze.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the squeeze gizmo.

<Squeeze.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the squeeze gizmo.

<Squeeze.Gizmo>.scale Point3 default: [1,1,1] -- animatable

The scale of the squeeze gizmo.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


STL_Check : Modifier

Constructor

stl_check ...

Properties

<STL_Check>.Selection_Type Integer default: 4

Selects incorrect geometry specific to the following settings:

0- Open Edge (Checks for open edges.)

1- Double Face (Checks for faces that share the same 3D space.)

2- Spike (Checks for spikes, which are isolated faces that share only one edge with the object.)

3- Multiple Edge (Checks for faces that share more than one edge.)

4- 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:

0- Don't Select (When on, STL Check doesn't select any part of objects in error.)

1- 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.)

2- 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.

0- Off

1- On

<STL_Check>.Change_MatID Integer default: 1

When on, STL Check also marks faces in error by assigning them a unique material ID.

0- Off

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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:

0- X

1- Y

2- Z

<Stretch>.limit Boolean default: false

When on, the stretch effect is limited by the from and to values.

<Stretch>.from Float default: 0.0 -- animatable

The boundary of the stretch effect along the negative Stretch Axis.

<Stretch>.to Float default: 0.0 -- animatable

The boundary of the stretch effect along the positive Stretch Axis.

<Stretch>.center Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center, altering the Stretch gizmo's shape, and thus the shape of the stretched object.

<Stretch>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Stretch modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.

<Stretch.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the stretch gizmo.

<Stretch.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the stretch gizmo.

<Stretch.Gizmo>.scale Point3 default: [1,1,1] -- animatable

The scale of the stretch gizmo.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SurfDeform : Modifier

Constructor

surfDeform ...

Properties

<SurfDeform>.surface Node default: undefined

The surface used to apply deformation.

<SurfDeform>.U_Percent Float default: 50.0 -- animatable, percentage

Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage of the U distance. This defaults to a setting of 50 percent, which places the object at the center of the gizmo patch. A setting of 0 percent places the object at the left edge of the gizmo patch, as seen from the viewport where the patch was created.

<SurfDeform>.U_Stretch Float default: 1.0 -- animatable

Scales the object along the U (horizontal) axis of the gizmo patch.

<SurfDeform>.V_Percent Float default: 50.0 -- animatable, percentage

Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.

<SurfDeform>.V_Stretch Float default: 1.0 -- animatable

Scales the object along the V (vertical) axis of the gizmo patch.

<SurfDeform>.rotation Float default: 0.0 -- animatable, angle

Rotates the modified object with respect to the gizmo patch.

<SurfDeform>.Plane_to_Patch_Deform Integer default: 0

Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch:

0- XY

1- YZ

2- ZX

<SurfDeform>.Flip_deformation_axis Integer default: 0

When on, reverses the gizmo direction.

0- Don't flip

1- Flip

<SurfDeform>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the modifier. The PatchDeform gizmo is a representation of the deforming patch object, so transforming it determines which part of the patch affects the modified object.

<SurfDeform.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the surfdeform gizmo.

<SurfDeform.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the surfdeform gizmo.

<SurfDeform.Gizmo>.scale Point3 default: [1,1,1] -- animatable

The scale of the surfdeform gizmo.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Taper : Modifier

Constructor

taper ...

Properties

<Taper>.amount Float default: 1.0 -- animatable

The extent to which the ends are scaled. Amount is a relative value with a maximum of 10.

<Taper>.curve Float default: 0.0 -- animatable, alias: curvature

Applies a curvature to the sides of the Taper gizmo, thus affecting the shape of the tapered object. Positive values produce an outward curve along the tapered sides, negative values an inward curve. At 0, the sides are unchanged.

<Taper>.primaryaxis Integer default: 2

The central axis or spine of the taper:

0- X

1- Y

2- Z

<Taper>.effectaxis Integer default: 2

The axis, or pair of axes, indicating the direction of the taper from the primary axis. The available choices are determined by the choice of primary axis. The effect axis can be either of the two remaining axes, or their combination. If the primary axis is X, the effect axis can be Y, Z, or YZ.

0- Z

1- Y

2- ZY

<Taper>.symmetry Boolean default: false -- animatable

When on, produces a symmetrical taper around the primary axis. A taper is always symmetrical around the effect axis.

<Taper>.limit Boolean default: false

Enables/disables upper and lower limits for the taper effect.

<Taper>.upperlimit Float default: 0.0 -- animatable, alias: Upper_Limit

The upper limit boundaries in world units from the taper center point, beyond which the taper no longer affects the geometry.

<Taper>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit

The lower limit boundaries in world units from the taper center point, beyond which the taper no longer affects the geometry.

<Taper>.center Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center, altering the Taper gizmo's shape, and thus the shape of the melted object

<Taper>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Taper modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.

<Taper.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the taper gizmo.

<Taper.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the taper gizmo.

<Taper.Gizmo>.scale Point3 default: [1,1,1] -- animatable

The scale of the taper gizmo.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Tessellate : Modifier

Constructor

tessellate ...

Properties

<Tessellate>.tension Float default: 2500.0 -- animatable, percentage

Determines if the new faces are flat, concave, or convex after Edge tessellation. A positive value rounds faces by pushing vertices outward. A negative value creates concave faces by pulling vertices inward. A setting of 0 keeps the faces flat.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Trim_Extend : Modifier

Constructor

trim_extend ...

Properties

There are no additional properties for Trim_Extend.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Twist : Modifier

Constructor

twist ...

Properties

<Twist>.angle Float default: 0.0 -- animatable

The amount of twist around the vertical axis.

<Twist>.bias Integer default: 0 -- animatable

Causes the twist rotation to bunch up at either end of the object. When the parameter is negative, the object twists closer to the gizmo center. When the value is positive, the object twists more away from the gizmo center. When the parameter is 0, the twisting is uniform.

<Twist>.axis Integer default: 2

The axis along which the twist will occur. This is the local axis of the Twist gizmo.

0- X

1- Y

2- Z

<Twist>.limit Boolean default: false

When on, applies limit constraints to the Twist modifier.

<Twist>.upperlimit Float default: 0.0 -- animatable, alias: Upper_Limit

The upper limit for the twist effect.

<Twist>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit

The lower limit for the twist effect.

<Twist>.center Point3 default: [0,0,0] -- animatable

You can translate and animate the center at this sub-object level, altering the Twist gizmo's shape, and thus the shape of the twisted object.

<Twist>.gizmo SubAnim

You can transform and animate the gizmo like any other object at this sub-object level, altering the effect of the Twist modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.

<Twist.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the twist gizmo.

<Twist.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the twist gizmo.

<Twist.Gizmo>.scale Point3 default: [1,1,1] -- animatable

The scale of the twist gizmo.

See also

Modifier Sub-Object Transform Properties

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

SetMapChannel <channel>

Sets the Map Channel field in the rollup

Channel (integer) – The channel that you want to set to.

GetMapChannel()

Returns the Map Channel field value in the rollup

SetVC <VertexColor>

Sets the Vertex Color Channel radio button in the rollup on or off.

VertexColor (integer) – Turn the vertex color on/off.

GetVC()

Returns the state of the Vertex Color Channel radio button in the rollup.

SetProjectionType <Proj>

Proj (integer) – The type of mapping you want:

1 – X aligned

2 – Y aligned

3 – Z aligned

4 – normal aligned

GetProjectionType()

Returns the state of the mapping align radio buttons:

1 – X aligned

2 – Y aligned

3 – Z aligned

4 – normal aligned

Move()

Presses the Move button in the edit floater.

MoveH()

Presses the Move Horizontal button in the edit floater.

MoveV()

Presses the Move Vertical button in the edit floater.

Rotate()

Presses the Rotate button in the edit floater.

Scale()

Presses the Scale button in the edit floater.

ScaleH()

Presses the Scale Horizontal button in the edit floater.

ScaleV()

Presses the Scale Vertical button in the edit floater.

MirrorH()

Presses the Mirror Horizontal button in the edit floater.

MirrorV()

Presses the Mirror Vertical button in the edit floater.

ExpandSelection()

Presses the Expand Selection button in the edit floater.

ContractSelection()

Presses the Contract Selection button in the edit floater

SetFalloffType <falloff>

Sets the falloff type in the edit floater.

falloff (integer) – The falloff type:

1 – Linear falloff

2 – Sinual falloff

3 – Fast falloff

4 – Slow falloff

GetFalloffType()

Returns the falloff type in the edit floater:

1 – Linear falloff

2 – Sinual falloff

3 – Fast falloff

4 – Slow falloff

SetFalloffSpace <space>

Sets the falloff space in the edit floater.

space (integer) – The space you want the falloff to be computed in:

1 – XY (The local space of the object.)

2 – UV (The UVW space of the object.)

GetFalloffSpace()

Returns the falloff space in the edit floater.

SetFalloffDist <dist>

Sets the falloff distance in the edit floater.

dist (float) – The falloff distance.

GetFalloffDist()

Returns the falloff distance from the edit floater.

BreakSelected()

Presses the Break Selected button in the edit floater.

Weld()

Presses the Target Weld button in the edit floater.

WeldSelected()

Presses the Weld Selected button in the edit floater.

Updatemap()

Presses the Update Map button in the edit floater.

Displaymap <DisplayMap>

Toggles the Display Map button in the edit floater.

DisplayMap (boolean) – The state that you want to set the Display Map to.

IsMapDisplayed()

Returns the state of the Display Map button.

SetUVSpace <UVspace>

Sets the UV Space fly out in the edit floater.

UVSpace (integer) – The space that you want to view the texture vertices in:

1 – UV

2 – VW

3 – UW

GetUVSpace()

Returns the state of the UV Space fly out in the edit floater:

1 – UV

2 – VW

3 – UW

Options()

Presses the Options button in the edit floater.

Lock()

Toggles the Lock Selected Vertices button in the edit floater.

Hide()

Presses the Hide button in the edit floater.

Unhide()

Presses the Unhide button in the edit floater.

Freeze()

Presses the Freeze button in the edit floater.

Thaw()

Presses the Unfreeze button in the edit floater

FilterSelected()

Toggles the Filter Selected Faces button in the edit floater.

Pan()

Presses the Pan button in the edit floater.

Zoom()

Presses the Zoom button in the edit floater.

ZoomRegion()

Presses the Zoom Region button in the edit floater.

Fit()

Presses the Fit button in the edit floater.

FitSelected()

Presses the Fit Selected button in the edit floater.

Snap()

Presses the Snap button in the edit floater.

GetCurrentMap()

Returns the index into the map drop down list of the current map in the view of the edit floater.

SetCurrentMap <map>

Changes the currently displayed map to the index provided.

map (integer) – The index of the map in the drop down list that you want to display.

NumberMaps()

Returns the number of maps in the map drop down list.

GetLineColor()

Returns the color of the lines used to connect the texture vertices edges as a Point3 value.

SetLineColor <color>

Sets the line color of the texture vertices.

color (point3) – The color that you want to set the lines to.

GetSelColor()

Returns the texture vertices selection color as a Point3 value.

SetSelColor <color>

Sets the color of selected texture vertices.

color (point3) – The color that you want the selected vertice to be.

GetRenderWidth <dist>

Returns the width of the bitmap used to render 2d/3d textures to.

SetRenderWidth <width>

Sets the width of the bitmap used to render to for display.

width (integer) – The width in pixels for the bitmap.

GetRenderHeight()

Returns the height of the bitmap used to render 2d/3d textures to.

SetRenderHeight <height>

Sets the width of the bitmap used to render to the display.

height (integer) - The height in pixels for the bitmap.

GetUseBitmapRes()

Returns the state of the Use Bitmap Resolution as a boolean value. If false, the bitmaps are rendered using the RenderWidth/Height values.

SetUseBitmapRes <useBitmapRes>

Sets the state of the Use Bitmap Resolution value. If it is false the bitmaps are rendered using the RenderWidth/Height values.

UseBitmapRes (boolean) - Toggle Use Bitmap Resolution.

GetWeldThresold()

Returns the weld threshold

SetWeldThreshold <threshold>

Sets the threshold values for welds.

threshold (float) – Threshold for welds.

GetConstantUpdate()

Returns the state of Constant Update as a boolean value. When true, viewport is updated on every move, otherwise it is just updated on mouse up.

SetConstantUpdate <constantUpdates>

Sets the state of the Constant Update value. When true, the viewport is updated on every move, otherwise it is just updated on mouse up.

GetShowSelectedVertices()

Returns a boolean value which indicates whether the selected texture vertices are also displayed in the view port.

SetShowSelectedVertices <show>

Sets whether the selected texture vertices are also displayed in the viewport.

show (boolean) – The state of Show Selected Vertices.

GetMidPixelSnape()

Returns a boolean value which indicated whether the mid pixels snap is used, if it is false the snap is set to the bottom right corner of the pixel, else it snaps to the center of the pixel.

SetMidPixelSnape <snap>

Sets whether mid pixels snap is used. When false, the snap is set to the bottom right corner of the pixel. When true, it snaps to the center of the pixel.

snap (boolean) – The mid pixel snap state to be set.

GetMatID()

Returns the current material id index filter.

SetMatID <matid>

Sets the material drop list to the index supplied.

matid (integer) – The material id index to be set.

NumberMatIDs()

Returns the number of material ids in the material id filter drop down.

GetSelectedVerts()

Returns the current selected texture vertices in the edit floater as a bitarray.

SelectVerts <sel>

Selects texture vertices in the edit floater dialog.

sel (bitarray) – The selection set.

IsVertexSelected <index>

Returns a boolean value which indicates whether a texture vertex is selected.

index (integer) – The index of the vertex to check.

MoveSelectedVertices <offset>

Moves the selected texture vertices by the offset.

offset (point3) - The offset by which you want to move the vertices.

RotateSelectedVertices <angle>

Rotates the selected vertices around their center point.

angle (float) – The angle in radians that you want to rotate the selection by.

RotateSelectedVertices <angle> <axis>

Rotates the selected vertices around a specific axis.

angle (float) – The angle in radians that you want to rotate the selection by.

axis (point3) – The axis that you want to rotate the selected vertices by. This is in the space of the window.

ScaleSelectedVertices <scale> <dir>

Scales the selected points around their center.

scale (float) – The amount that you want to scale by.

dir (integer) – The direction you want to scale by:

0 – Scales uniform

1 – Scales in the x

2 – Scales in the y

ScaleSelectedVertices <scale> <dir> <axis>

Scales the selected points around their center around the axis.

scale (float) – The amount that you want to scale by.

dir (integer) – The direction:

0 – Scales uniform

1 – Scales in the x

2 – Scales in the y

axis (point3) – The axis that you want to rotate the selected vertices by. This is in the space of the window.

GetVertexPosition <time> <index>

Returns the position of the vertex as a Point3 value.

time (timevalue) – The time at which you wan to check.

index (integer) – The index of the vertex.

NumberVertices()

Returns the number of texture vertices.

MoveX <p>

This sets the selected vertices x values in absolute coordinates.

p (float) – The absolute position along the x axis.

MoveY <p>

This sets the selected vertices y values in absolute coordinates.

p (float) – The absolute position along the y axis.

MoveZ <p>

This sets the selected vertices xzvalues in absolute coordinates.

p (float) – The absolute position along the z axis.

GetSelectedPolygons()

Returns the selected polygons in the view port as a bitarray.

SelectPolygons <sel>

Selects the polygons in the view ports.

sel (bitarray) – The polygons to select.

IsPolygonSelected <index>

Returns whether a polygon is selected or not.

index (integer) – Index of the polygon to check.

NumberPolygons()

Returns the number of polygons in the object.

DetachEdgeVerts()

Detaches any vertex that is not completely surrounded by selected vertices. This is similar to a polygon selection detach except it uses the vertex selection to determine what is detached.

FlipH()

This presses the Flip Horizontal button in the edit floater dialog.

FlipV()

This presses the Flip Vertical button in the edit floater dialog.

GetLockAspect()

Returns whether the edit window aspect ratio is locked or not. If the aspect ratio is not locked the image will try stretch to fit the aspect ratio of the window.

SetLockAspect <aspect>

This sets the Lock Aspect Ratio value.

aspect (boolean) – Aspect lock toggle.

GetMapScale()

Returns the scaling factor when the user applies a planar map. The smaller the value the more planar map is scaled down

SetMapScale <scale>

Sets the scaling factor when the user applies a planar map. The smaller the value the more planar map is scaled down.

scale (float) - The scaling factor for planar map.

GetSelectionFromFace()

This takes the current polygon selection and uses it to select the texture vertices that are associated with it.

ForceUpdate <update>

This sets a flag to determines how Unwrap will behave when a topology change occurs. If update is TRUE the mapping gets reset, otherwise unwrap skips mapping the object if it has a different topology. It is sometimes useful to turn this off if you have MeshSmooth or other topology changing modifiers below Unwrap that have different topologies when rendering.

update (boolean) – Determines whether the mapping is reset on topology change.

ZoomToGizmo <all>

This zooms the selected or all the viewports to zoom to the current planar map gizmo.

all (boolean) – Determines whether the active or all the viewports get zoomed.

UpdateView()

This forces the viewport and dialog to update.

SetVertexPosition <t> <index> <pos>

This sets the position of a UVW vertex at a specific time.

t (timeValue) – The time at what you want to set the pos.

index (integer) – The index of the vertex.

pos (point3) – The position of the vertex in UVW space.

The functions below work on the UVW topology allowing you to rearrange the topology or add new topology. Use these with care since you can create invalid topology which can cause unpredictable results. Unwrap has topology similar to meshes but it has been changed to support everything except patches and polygons at the same time. Unwrap has a list of Point3 values which are the texture vertices positions. Then there are texture faces which contain an array of integers which are indices into the texture vertex list. There can be 3 to N number of ints in this array depending on the topology being fed into Unwrap. In addition to this, there are also 2 arrays of integers for the handles and interior handles if the topology is a patch which also points into the texture vertex list. The functions below allow you to manipulate these arrays to do things like break, weld, and other topological functions.

MarkAsDead <index>

This marks a vertex that it is dead, and no longer in use. Vertices are not actually deleted they are just marked and recycled when needed. That means that when a vertex is added vertices marked as dead will be the first ones checked. If there are no dead vertices, the vertex is appended to the end of the list. Use this function carefully, since marking a vertex in use as dead will cause strange results.

index (integer) – The index of the vertex to mark as dead.

NumberPointsInFace <index>

This retrieves the numbers of vertices that a face contains. A face can contain 3 to N number of points depending on what type of topology Unwrap is working on. For Tri Meshes this is always 3; for patches this can be 3 or 4; and for polygons this can be 3 or greater. Unwrap abstracts all three object types into one generic format.

index (integer) – The index of the face that you are inspecting.

GetVertexIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a vertex, from a face. A face contains 0 to N number of vertices, so to retrieve a particular vertex index, you give it the face index and the ith vertex that you want to inspect. For example, if you wanted to look at the 3 vertex on face 1 you would call GetVertexIndexFromFace (1,3).

FaceIndex (integer) – The index of the face that you want to inspect.

IthVertexIndex (integer) – The ith vertex of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.

GetHandleIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a handle, from a face, which contains 0 to N number of handles. To retrieve a particular handle index, you give it the face index and the ith handle that you want to inspect. For example, if you wanted to look at the 3 handle on face 1 you would call GetHandleIndexFromFace (1,3). This only applies to patch meshes.

FaceIndex (integer) – The index of the face that you want to inspect.

IthVertexIndex (integer) – The ith handle of that you want to retrieve. This value should range from 1 to the twice the number of vertices that the face contains.

GetInteriorIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a interior handle from a face. A face contains 0 to N number of interior handles, so to retrieve a particular interior handle index, you give it the face index and the ith interior handle that you want to inspect. For example, if you wanted to look at the 3 interior handle on face 1 you would call GetInteriorIndexFromFace (1,3). This only applies for patch meshes.

FaceIndex (integer) – The index of the face that you want to inspect.

IthVertexIndex (integer) – The ith interior handle of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.

GetVertexGIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a geometric vertex from a face. This the vertex that is attached to the mesh and not the texture faces. A face contains 0 to N number of vertices, so to retrieve a particular vertex index, you give it the face index and the ith vertex that you want to inspect. For example, if you wanted to look at the 3 vertex on face 1 you would call GetVertexGeomIndexFromFace (1,3).

FaceIndex (integer) – The index of the face that you want to inspect.

IthVertexIndex (integer) – The ith vertex of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.

GetHandleGIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a geometric handle from a patch. This the handle that is attached to the patch and not the texture faces. A face contains 0 to N number of handles, so to retrieve a particular handle index, you give it the face index and the ith handle that you want to inspect. For example, if you wanted to look at the 3 handle on face 1 you would call GetHandleGeomIndexFromFace(1,3).

FaceIndex (integer) – The index of the face that you want to inspect.

IthVertexIndex (integer) – The ith handle of that you want to retrieve. This value should range from 1 to twice the number of vertices that the face contains.

GetInteriorGIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a geometric interior handle from a patch. This the interior handle that is attached to the patch and not the texture faces. A face contains 0 to N number of interior handles, so to retrieve a particular interior handle index, you give it the face index and the ith interior handle that you want to inspect. For example, if you wanted to look at the 3 interior handle on face 1 you would call GetInteriorGeomIndexFromFace (1,3).

FaceIndex (integer) – The index of the face that you want to inspect.

IthVertexIndex (integer) – The ith interior handle of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.

SetFaceVertex <pos> <fIndex> <vIndex> <sel>

This allows you to manipulate the position of vertex attached to a face. Basically, it detaches the vertex if multiple faces share that vertex and then moves it to the position specified. So if you want to move the 3rd vertex of face 1 to (.5,.5,.0) you would do setFaceVertex [.5 .5 .0] 1 3. If you don't want the vertex broken use SetVertexSPosition.

pos (point3) - The position that you want to move a vertex to.

fIndex (integer) – The index of the face that you wish to work on.

vIndex (integer) – The ith vertex of the face that you want to change.

sel (boolean) – Whether or not to select the vertex after it is recreated.

SetFaceHandle <pos> <fIndex> <vIndex> <sel>

Identical to SetFaceVertex except works on patch handles.

pos (point3) - The position that you want to move a vertex to.

fIndex (integer) – The index of the face that you wish to work on.

vIndex (integer) – The ith vertex of the face that you want to change.

sel (boolean) – Whether or not to select the vertex after it is recreated.

SetFaceInterior <pos> <fIndex> <vIndex> <sel>

Identical to SetFaceVertex except works on patch interior handles.

pos (point3) - The position that you want to move a vertex to.

fIndex (integer) – The index of the face that you wish to work on.

vIndex (integer) – The ith vertex of the face that you want to change.

sel (boolean) – Whether or not to select the vertex after it is recreated.

SetFaceVertexIndex <fIndex> <ithV> <vIndex>

This allows you to set the index of the ith vertex of a face. For example, if you wanted to change the index of the 3rd vertex of face 1 to 100 you would call setFaceVertexIndex 1 3 100.

fIndex (integer) – Index of the face you want work on.

ithV (integer) – The ith vertex that you want to manipulate.

vIndex (integer) – The index into the vertex list that you want to set to.

SetFaceHandleIndex <fIndex> <ithV> <vIndex>

Identical to setFaceVertexIndex but works on handles for patches.

fIndex (integer) – Index of the face you want work on.

ithV (integer) – The ith vertex that you want to manipulate.

vIndex (integer) – The index into the vertex list that you want to set to.

SetFaceInteriorIndex <fIndex> <ithV> <vIndex>

Identical to setFaceVertexIndex but works on interior handles for patches.

fIndex (integer) – Index of the face you want work on.

ithV (integer) – The ith vertex that you want to manipulate.

vIndex (integer) – The index into the vertex list that you want to set to.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


UVW_Xform : Modifier

Constructor

uvw_xform ...

Properties

<UVW_Xform>.U_Tile Float default: 1.0 -- animatable

The tiling along the U-axis.

<UVW_Xform>.U_Flip Integer default: 0

When on, reverses the direction of the map along the U-axis.

0- Off

1- On

<UVW_Xform>.V_Tile Float default: 1.0 -- animatable

The tiling along the V-axis.

<UVW_Xform>.V_Flip Integer default: 0

When on, reverses the direction of the map along the V-axis.

0- Off

1- On

<UVW_Xform>.W_Tile Float default: 1.0 -- animatable

The tiling along the W-axis.

<UVW_Xform>.W_Flip Integer default: 0

When on, reverses the direction of the map along the W-axis.

0- Off

1- On

<UVW_Xform>.U_Offset Float default: 0.0 -- animatable

Offsets the map along the U-axis.

<UVW_Xform>.V_Offset Float default: 0.0 -- animatable

Offsets the map along the V-axis.

<UVW_Xform>.W_Offset Float default: 0.0 -- animatable

Offsets the map along the W-axis.

<UVW_Xform>.Map_or_Vertex_Color Integer default: 0

Specifies whether to apply the transform to a mapping channel or a vertex color channel:

0- Map Channel

1- Vertex Color Channel

Notes

The Map Channel property is not accessible by MAXScript in 3ds max 4.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


UVWmap : Modifier

Constructor

uvwmap ...

Properties

<Uvwmap>.maptype Integer default: 0

Determines the type of mapping coordinates used. Different kinds of mapping are distinguished by how the map is geometrically projected onto the object and how the projection interacts with the object's surfaces.

0- 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.)

1- 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.)

2- 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.)

3- 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.)

4- 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.)

5- 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.)

6- XYZ to UVW (Maps 3D procedural coordinates to UVW coordinates. This "sticks" the procedural texture to the surface. If the surface stretches, so does the 3D procedural map.)

<Uvwmap>.cap Boolean default: false

When on, applies planar mapping coordinates to the caps of the cylinder.

<Uvwmap>.length Float default: 1.0 -- animatable

The length of the UVW mapping gizmo.

<Uvwmap>.width Float default: 1.0 -- animatable

The width of the UVW mapping gizmo.

<Uvwmap>.height Float default: 1.0 -- animatable

The height of the UVW mapping gizmo.

<Uvwmap>.utile Float default: 1.0 -- animatable, alias: U_Tile

The tiling of the UVW map along the U-axis.

<Uvwmap>.uflip Boolean default: false

When on, reverses the image about the U-axis.

<Uvwmap>.vtile Float default: 1.0 -- animatable, alias: V_Tile

The tiling of the UVW map along the V-axis.

<Uvwmap>.vflip Boolean default: false

When on, reverses the image about the V-axis.

<Uvwmap>.wtile Float default: 1.0 -- animatable, alias: W_Tile

The tiling of the UVW map along the W-axis.

<Uvwmap>.wflip Boolean default: false

When on, reverses the image about the W-axis.

<Uvwmap>.channel Integer default: 0

Specifies whether to apply the transform to a mapping channel or a vertex color channel:

0- Map Channel

1- Vertex Color Channel

<Uvwmap>.mapChannel Integer default: 1

The map channel used to apply mapping transforms.

<Uvwmap>.axis Integer default: 2

Specifies which axis of the gizmo is aligned with the local Z-axis of the object:

0- X

1- Y

2- Z

<Uvwmap>.gizmo SubAnim

Enables gizmo transformations. Turn on and then move, scale, and rotate the gizmo in the viewports to position the map. In the Material Editor, you turn on the Show Map in Viewport option to make the map visible in a shaded viewport, the map moves on the surface of the object as you transform the gizmo.

<Uvwmap.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the UVWmap gizmo.

<Uvwmap.Gizmo>.rotation Quat default: (quat 0 0 -1 0) -- animatable

The rotation of the UVWmap gizmo.

<Uvwmap.Gizmo>.scale Point3 default: [1,1,1] -- animatable

The scale of the UVWmap gizmo.

Notes

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

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


VolumeSelect : Modifier

Constructor

volumeselect ...

Properties

<Volumeselect>.level Integer default: 0

Volume Select provides three selection levels. Vertex and Face levels put the modifier stack in sub-object selection. You can make one sub-object selection for each Volume Select modifier. You can then toggle the one selection between Face and Vertex level to send either up the stack. Object (top) level lets you modify the whole object while retaining any sub-object selection.

0- Object

1- Vertex

2- Face

<Volumeselect>.type Integer default: 0

Sets the volume select type:

0- Replace (Clears any selection passed up the stack to the Volume Select modifier, and then selects geometry within the volume.)

1- Add (Selects all geometry within the volume, adding to any previous selection.)

2- Subtract (Deselects all geometry within the volume.)

<Volumeselect>.invert Boolean default: false

When on, the entire selection set is reversed. Geometry that was unselected becomes selected, and vice versa.

<Volumeselect>.method Integer default: 0

Lets you determine whether selected faces are wholly or partially within the defined volume:

0- Window (Selects only faces with all three vertices within the selection volume.)

1- Crossing (Selects faces with only one vertex within the selection volume.)

<Volumeselect>.volume Integer default: 0

These controls let you define the selection with a primitive, a mesh object, or by surface characteristics:

0- Box

1- Sphere

2- Cylinder

3- Mesh Object

4- Texture Map

5- Material Id

6- Smoothing Group

<Volumeselect>.Node Node default: undefined

The node which defines the selection space when .volume is set to 3 (mesh object).

<Volumeselect>.matID Integer default: 1 -- alias: Material_ID

When .volume is set to 5 (material ID), all faces or vertices using the material ID specified by this value are selected.

<Volumeselect>.smGroup Integer default: 1 -- alias: Smoothing_Group

When .volume is set to 6 (smoothing group), all faces or vertices using the smoothing group specified by this value are selected.

<Volumeselect>.texture TextureMap default: undefined -- alias: TextureMap

When .volume is set to 4 (texture map), this texture map will define the selection space.

<Volumeselect>.map Integer default: 0 -- alias: Map_Channel_Type

Specifies whether to apply the selection by mapping channel or vertex color channel:

0- Map Channel

1- Vertex Color Channel

<Volumeselect>.mapChannel Integer default: 1 -- alias: Map_Channel

Specifies which map channel to use when .map is set to 0.

<Volumeselect>.autofit Boolean default: true -- alias: Auto_fit

When on, automatically adjusts the gizmo size and shape to fit the object as you change the underlying topology.

<Volumeselect>.UseAffectRegion Boolean default: false -- alias: Use_affect_region

When on, a soft selection region is applied.

<Volumeselect>.falloff Float default: 20.0 -- animatable

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry.

<Volumeselect>.pinch Float default: 0.0 -- animatable

Raises and lowers the top point of the curve along the vertical axis. Sets the relative "pointedness" of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis.

<Volumeselect>.bubble Float default: 0.0 -- animatable

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

<Volumeselect>.center Point3 default: [0,0,0] -- animatable

You can translate and animate the center, which affects rotation or scaling of the Volume Select modifier's gizmo.

<Volumeselect>.gizmo SubAnim

You can transform and animate the gizmo to change the selection. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.

<Volumeselect.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the volumeselect gizmo.

<Volumeselect.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the volumeselect gizmo.

<Volumeselect.Gizmo>.scale Point3 default: [1,1,1] -- animatable

The scale of the volumeselect gizmo.

Notes

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

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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.

<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

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


XForm : Modifier

Constructor

xform ...

Properties

<XForm>.center Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center, altering the Xform gizmo's shape, and thus the shape of the object.

<XForm>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Xform modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.

<XForm.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the wave gizmo.

<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

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Spacewarp Binding SpacewarpModifiers

The SpaceWarp Binding SpacewarpModifiers are not directly created in MAXScript, but are rather created and applied to a node using the bindSpaceWarp() method. Most of the SpacewarpModifiers do not have any additional properties.

Constructors and Properties

SimpleOSMToWSMMod:

bindSpaceWarp <node> <spaceBend_node>

bindSpaceWarp <node> <spaceNoise_node>

bindSpaceWarp <node> <spaceSkew_node>

bindSpaceWarp <node> <spaceStretch_node>

bindSpaceWarp <node> <spaceTaper_node>

bindSpaceWarp <node> <spaceTwist_node>

BombBinding:

bindSpaceWarp <node> <bomb_node>

DeflectorBinding:

bindSpaceWarp <particlesys_node> <deflector_node>

DisplaceBinding:

bindSpaceWarp <node> <spaceDisplace_node>

FFD_Binding:

bindSpaceWarp <node> <spaceFFDBox_node>

bindSpaceWarp <node> <spaceFFDCyl_node>

GravityBinding:

bindSpaceWarp <node> <gravity_node>

MotorMod:

bindSpaceWarp <node> <motor_node>

PathFollowMod:

bindSpaceWarp <particlesys_node> <path_Follow_node>

PBombMod:

bindSpaceWarp <node> <pbomb_node>

PDynaFlectMod:

bindSpaceWarp <node> <PDynaFlect_node>

POmniFlectMod:

bindSpaceWarp <particlesys_node> <POmniFlect_node>

PushMod:

bindSpaceWarp <node> <pushSpaceWarp_node>

RippleBinding:

bindSpaceWarp <node> <spaceRipple_node>

<RippleBinding>.Flexibility Float default: 1.0 -- animatable

SDeflectMod:

bindSpaceWarp <particlesys_node> <sdeflector_node>

SDynaFlectMod:

bindSpaceWarp <node> <SDynaFlect_node>

SOmniFlectMod:

bindSpaceWarp <particlesys_node> <SOmniFlect_node>

SpaceConform:

bindSpaceWarp <node> <conformSpaceWarp_node>

UDeflectorMod:

bindSpaceWarp <particlesys_node> <uDeflector_node>

UDynaFlectMod:

bindSpaceWarp <node> <UDynaFlect_node>

UOmniFlectMod:

bindSpaceWarp <particlesys_node> <UOmniFlect_node>

WaveBinding:

bindSpaceWarp <node> <spaceWave_node>

<WaveBinding>.Flexibility Float default: 1.0 -- animatable

WindBinding:

bindSpaceWarp <node> <wind_node>

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Displace_Mesh : SpacewarpModifier

Constructor

displace_Mesh ...

Properties

There are no additional properties for Displace_Mesh.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Displace_NURBS : SpacewarpModifier

Constructor

displace_NURBS ...

Properties

There are no additional properties for Displace_NURBS.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


MapScaler : SpacewarpModifier

Constructor

MapScaler ...

Properties

<MapScaler>.scale Float default: 100.0 -- animatable

The size of one repeat of the texture pattern. Size is measured in current scene units. Repeats occur across the object in the U direction.

<MapScaler>.channel Integer default: 1

The map channel used.

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

0- Off

1- On

<MapScaler>.Up_Direction Integer default: 1

Sets the map alignment:

0- World Z Axis (Aligns the map with the Z axis of the world.)

1- Local Z Axis (Aligns the map with the local Z axis of the object.)

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SpaceCameraMap : SpacewarpModifier

Constructor

SpaceCameraMap ...

Properties

<SpaceCameraMap>.camera Node default: undefined

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SpacePatchDeform : SpacewarpModifier

Constructor

SpacePatchDeform ...

Properties

<SpacePatchDeform>.U_Percent Float default: 50.0 -- animatable, percentage

Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage of the U distance. This defaults to a setting of 50 percent, which places the object at the center of the gizmo patch. A setting of 0 percent places the object at the left edge of the gizmo patch, as seen from the viewport where the patch was created.

<SpacePatchDeform>.U_Stretch Float default: 1.0 -- animatable

Scales the object along the U (horizontal) axis of the gizmo patch.

<SpacePatchDeform>.V_Percent Float default: 50.0 -- animatable, percentage

Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.

<SpacePatchDeform>.V_Stretch Float default: 1.0 -- animatable

Scales the object along the V (vertical) axis of the gizmo patch.

<SpacePatchDeform>.rotation Float default: 0.0 -- animatable, angle

Rotates the modified object with respect to the gizmo patch.

<SpacePatchDeform>.Plane_to_Patch_Deform Integer default: 0

Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch:

0- XY

1- YZ

2- ZX

<SpacePatchDeform>.Flip_deformation_axis Integer default: 0

When on, reverses the gizmo direction:

0- Off

1- On

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SpacePathDeform : SpacewarpModifier

Constructor

SpacePathDeform ...

Properties

<SpacePathDeform>.path Node default: undefined

The node designated as the path.

<SpacePathDeform>.Percent_along_path Float default: 0.0 -- animatable, percentage

Moves the object along the gizmo path based on a percentage of the path length.

<SpacePathDeform>.Stretch Float default: 1.0 -- animatable

Scales the object along the gizmo path, using the object's pivot point as the base of the scale.

<SpacePathDeform>.rotation Float default: 0.0 -- animatable, angle

Rotates the object about the gizmo path.

<SpacePathDeform>.Twist Float default: 0.0 -- animatable, angle

Twists the object about the path. The twist angle is based on the rotation of one end of the overall length of the path. Typically, the deformed object takes up only a portion of the path, so the effect can be subtle.

<SpacePathDeform>.axis Integer default: 2

Choose one to rotate the gizmo path to align with a specified local axis of the object:

0- X

1- Y

2- Z

<SpacePathDeform>.Flip_deformation_axis Integer default: 0

When on, reverses the gizmo path 180 degrees about the specified axis.

0- Off

1- On

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SpaceSurfDeform : SpacewarpModifier

Constructor

SpaceSurfDeform ...

Properties

<SpaceSurfDeform>.surface Node default: undefined

The surface used for deformation.

<SpaceSurfDeform>.U_Percent Float default: 50.0 -- animatable, percentage

Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage of the U distance. This defaults to a setting of 50 percent, which places the object at the center of the gizmo patch. A setting of 0 percent places the object at the left edge of the gizmo patch, as seen from the viewport where the patch was created.

<SpaceSurfDeform>.U_Stretch Float default: 1.0 -- animatable

Scales the object along the U (horizontal) axis of the gizmo patch.

<SpaceSurfDeform>.V_Percent Float default: 50.0 -- animatable, percentage

Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.

<SpaceSurfDeform>.V_Stretch Float default: 1.0 -- animatable

Scales the object along the V (vertical) axis of the gizmo patch.

<SpaceSurfDeform>.rotation Float default: 0.0 -- animatable, angle

Rotates the modified object with respect to the gizmo patch.

<SpaceSurfDeform>.Plane_to_Patch_Deform Integer default: 0

Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch:

0- XY

1- YZ

2- ZX

<SpaceSurfDeform>.Flip_deformation_axis Integer default: 0

Flip_deformation_axis = 0 - off; 1 - on

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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.

Notes

There is no way to specify the Source Texture Surface using MAXScript in 3ds max 4.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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 Material Types. 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 Material Common Properties, Operators, and Methods.

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 MAXWrapper.


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.

getMTLMEditFlags ( <material> | <texture> )

setMTLMEditFlags ( <material> | <texture> ) <bitarray>

Get and set the MEdit options for the specified material or texture as a <bitarray>. If a bit is on, the corresponding option is turned on. The order of the bits is: #{MTL_BEING_EDITED,BACKGROUND,BACKLIGHT,VIDEO_COLOR_CHECK}

The first bit is set if the rollout for the specified material or texture is currently displayed in the active MEdit slot. The state of this bit is ignored in setMTLMEditFlags().

getMTLMeditObjType ( <material> | <texture> )

setMTLMeditObjType ( <material> | <texture> ) <integer>

Get and set the MEdit sample object type for the specified material or texture. The valid values are: 1 - sphere; 2 - cylinder; 3 - cube; 4 - custom

getMTLMeditTiling ( <material> | <texture> )

setMTLMeditTiling ( <material> | <texture> ) <integer>

Get and set the MEdit tiling type for the specified material or texture. The valid values are: 1 - 1x1; 2 - 2x2; 3 - 3x3; 4 - 4x4

updateMTLInMedit ( <material> | <texture> )

Performs a set of 3ds max notifications that forces an update of the material or texture throughout 3ds max, including the MEdit and material browser.

You can get and set Material Editor materials using the getMeditMaterial() and setMeditMaterial() functions. You can also get a material from the Material Editor using the meditMaterials virtual array. See Material Editor and MaterialLibrary Values for more information.

See also

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Material Types

The following list displays the 3ds max material subclasses:

Blend

Composite

DoubleSided

MatteShadow

MorpherMaterial

MultiMaterial

NoMaterial

RaytraceMaterial

Shellac

Standard

TopBottom


Blend : Material

Constructor

blend ...

Properties

<blend>.map1 Material default: Standard -- alias: Map_1

The first material to be blended.

<blend>.map1Enabled Boolean default: true -- alias: Map_1_Enable

Turn on/off the use of the first material in the blend.

<blend>.map2 Material default: Standard -- alias: Map_1

the second material to be blended.

<blend>.map2Enabled Boolean default: true -- alias: Map_2_Enable

Turn on/off

<Blend>.mask TextureMap default: undefined

Selects a map to use as a mask. The two materials will blend in greater or lesser degree according to the intensity of the map. Lighter (whiter) areas of the mask show Material 1. Darker (blacker) areas of the mask show Material 2.

<blend>.maskEnabled Boolean default: true -- alias: MaskEnable

Enable/disable the use of the map mask.

<blend>.interactive Integer default: 0

Selects which of the two materials is displayed on object surfaces in viewports by the interactive renderer:

Material 1

Material 2

<blend>.mixAmount Float default: 0.0 -- animatable; percentage

The proportion of the blend (percentage). 0 means only Material 1 is visible on the surface; 100 means only Material 2 is visible.

<blend>.useCurve Boolean default: false

Determines whether the Mixing Curve affects the mix.

<blend>.upper Float default: 0.75 -- animatable

<blend>.lower Float default: 0.25 -- animatable

These values adjust the level of the Upper and Lower limits. If the two values are the same, the two materials meet at a definite edge. Wider ranges give more gradual blending from one sub-material to the other. The mixing curve displays the effect of changing these values.

See also

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


CompositeMaterial : Material

Constructor

compositeMaterial()

Properties

<compositematerial>.materialList Array default: #(Standard, undefined, ... , undefined, undefined) -- alias: Material

This array contains all of the materials included in the composite material.

<compositematerial>.mapEnables Array default: #(true, true, ... , true, true) -- alias: Map_Enable

This array turns on/off the use of materials (corresponding to the .materialList array) in the composite material.

<compositematerial>.mixType Array default: #(0, 0, ... , 0, 0) -- alias: Composite_Type

This array sets the mix type for each material in the .materialList of the composite material:

0- Additive

1- Subtractive

2- Mix

<compositematerial>.amount Array default: #(100.0, 100.0, ... , 100.0, 100.0) -- animatable

This array sets the amount of mixing for each corresponding material in the .materialList.

<compositematerial>.baseMaterial Standard Material default: (null) – alias for materialList[0]

S ets a base material for the composite material.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


DoubleSided : Material

Constructor

doubleSided ...

doubleSidedMat ...

Properties

<DoubleSided>.translucency Float default: 0.0 -- animatable

The amount that one material shows through the other. This is a percentage that can range from 0.0 to 100.0. At 100 percent, the outer material is visible on inner faces and the inner material is visible on outer faces. At intermediate values, the specified percentage of the inner material "bleeds through" and is visible on outer faces.

<DoubleSided>.material1 Material default: Standard -- alias: Material_1

The facing material.

<DoubleSided>.map1Enabled Boolean default: true -- alias: Map_1_Enable

Turn on/off display of the facing material.

<DoubleSided>.material2 Material default: Standard -- alias: Material_2

The back material.

<DoubleSided>.map2Enabled Boolean default: true -- alias: Map_2_Enable

Turn on/off display of the back material.

See also

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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:

0- 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.)

1- 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.

<MatteShadow>.shadowBrightness Float default: 0.0 -- animatable, alias: Shadow_Brightness

Sets shadow brightness. At 0.5, the shadows will not be attenuated on the matte surface; at 1.0, the shadows are brightened to the color of the matte surface; and at 0.0 they are darkened to completely obliterate the matte surface.

<MatteShadow>.color Color default: (color 0 0 0) -- animatable, alias: Shadow_Color

The color of the shadow.

<MatteShadow>.amount Float default: 50 -- animatable, percentage, alias: Reflection_Amount

The amount of reflection to use. This is a percentage that can range from 0 to 100.

<MatteShadow>.map TextureMap default: undefined

The map used for reflections.

<MatteShadow>.useReflMap Boolean default: true

Turns on/off the use of a reflection map.

See also

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


MorpherMaterial : Material

Constructor

morphermaterial ...

Note: This class is not available in 3D Studio VIZ.

Properties

<MorpherMaterial>.Channel_0 Float default: 0.0 -- animatable, percentage

<MorpherMaterial>.Channel_1 Float default: 0.0 -- animatable, percentage

<MorpherMaterial>.Channel_2 Float default: 0.0 -- animatable, percentage

...

<MorpherMaterial>.Channel_98 Float default: 0.0 -- animatable, percentage

<MorpherMaterial>.Channel_99 Float default: 0.0 -- animatable, percentage

<MorpherMaterial>.Channel_100 Float default: 0.0 -- percentage

Notes

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.

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


MultiMaterial : Material

Constructor

multimaterial [ numsubs:<integer> ]

multiSubMaterial [ numsubs:<integer> ]

Properties

<multimaterial>.numsubs

<multisubmaterial>.numsubs

the number of sub-materials in the multimaterial.

<multimaterial>.materialList ArrayParameter default: #(Standard, Standard, ... Standard, Standard)

<multisubmaterial>.materialList ArrayParameter default: #(Standard, Standard, ... Standard, Standard)

Stores the Material for each sub-material.

<multimaterial>.mapEnabled ArrayParameter default: #(true, true, ... true, true)

<multisubmaterial>.mapEnabled ArrayParameter default: #(true, true, ... true, true)

Stores whether the sub-material is enabled.

<multimaterial>.names ArrayParameter default: #("", "", ... "", "")

<multisubmaterial>.names ArrayParameter default: #("", "", ... "", "")

Stores the sub-material slot name (not the sub-material name).

<Multimaterial>.materialIDList ArrayParameter default: #(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) -- int array; Index

<Multisubmaterial>.materialIDList ArrayParameter default: #(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) -- int array; Index

Stores the sub-material ID's.

<Multimaterial>.material1 Standardmaterial default: Standard -- alias for materialList[0]; SubAnim

<Multisubmaterial>.material1 Standardmaterial default: Standard -- alias for materialList[0]; SubAnim

Stores the material.

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


RayTraceMaterial : Material

Constructor

rayTraceMaterial ...

Properties

<RaytraceMaterial>.Ambient_Color_On Float default: 0.0

If Ambient_Color_On = 0, Ambient_Amount is used, otherwise Ambient is used

<RaytraceMaterial>.Ambient Color default: (color 0 0 0) -- animatable

Sets the degree to which the material absorbs ambient light.

<RaytraceMaterial>.Ambient_Amount Float default: 0.0 -- animatable; percentage

The amount that the ambient map affects the material expressed as a percentage of full intensity.

<RaytraceMaterial>.Luminosity_Color_On Float default: 0.0

If Luminosity_Color_On = 0, Self_Illum__Amount is used, otherwise Luminosity is used

<RaytraceMaterial>.Luminosity Color default: (color 0 0 0) -- animatable

The self-illumination color of the material.

<RaytraceMaterial>.Self_Illum_Amount Float default: 0.0 -- animatable; percentage

The amount that the self-illumination map affects the material expressed as a percentage of full intensity.

<RaytraceMaterial>.Diffuse Color default: (color 127.5 127.5 127.5) -- animatable

Sets the diffuse color.

<RaytraceMaterial>.Transparency_Color_On Float default: 0.0

If Transparency_Color_On = 0, Transparency_Amount is used, otherwise Transparecy is used

<RaytraceMaterial>.Transparecy Color default: (color 0 0 0) -- animatable

The filter color of the material.

<RaytraceMaterial>.Transparency_Amount Float default: 0.0 -- animatable; percentage

The amount that the transparency map affects the material expressed as a percentage of full intensity.

<RaytraceMaterial>.Reflect_Color_On Float default: 0.0

If Reflect_Color_On = 0, Reflect_Amount is used, otherwise Reflect is used

<RaytraceMaterial>.Reflect Color default: (color 0 0 0) -- animatable

The specular reflection color.

<RaytraceMaterial>.Reflect_amount Float default: 0.0 -- animatable; percentage

The amount that the reflection map affects the material expressed as a percentage of full intensity.

<RaytraceMaterial>.Index_of_Refraction Float default: 100.0 -- animatable; percentage

The index of refraction (IOR) controls how severely the material refracts transmitted light. At 1.0, the IOR of air, the object behind the transparent object does not distort. At 1.5, the object behind distorts greatly, like a glass marble. At an IOR slightly less than 1.0, the object reflects along its edges, like a bubble seen from under water.

<RaytraceMaterial>.Spec__Color Color default: (color 255 255 255) -- animatable

Sets the color of specular highlights.

<RaytraceMaterial>.Specular_Level Float default: 50.0 -- animatable; percentage

Sets the intensity of specular highlights. Set the Specular Level to a very high value for very strong, tight highlights.

<RaytraceMaterial>.Glossiness Float default: 40.0 -- animatable; percentage

Affects the size of the specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier.

<RaytraceMaterial>.Soften Float default: 0.1 -- animatable

Softens the effect of highlights formed by glancing light.

<RaytraceMaterial>.Extra_Lighting Color default: (color 0 0 0) -- animatable

Adds light to the surface of objects with the Raytrace material.

<RaytraceMaterial>.translucency Color default: (color 0 0 0) -- animatable

Creates a translucent effect. The Translucency color is a non-directional diffuse reflection.

<RaytraceMaterial>.Fluorescence Color default: (color 0 0 0) -- animatable

Creates an effect similar to black light on a black light poster. The light from a black light is largely ultraviolet, outside the visible spectrum. Under black light, fluorescent paints flare or glow. The fluorescence in Raytrace material takes whatever light it sees in the scene, applies the Bias to it, and then, regardless of the color of the lights in the scene, illuminates the fluorescent material as if it were lit by white light.

<RaytraceMaterial>.Fluorescence_Bias Float default: 70.0 -- animatable; percentage

At 0.5, The Bias makes Fluorescence behave just like diffuse coloring. Bias values higher than 0.5 increase the fluorescent effect, making the object brighter than other objects in the scene. Bias values lower than 0.5 make the object dimmer than other objects in the scene.

<RaytraceMaterial>.Wire_Size Float default: 100.0 -- animatable; percentage

Sets the size of the wire in wireframe mode.

<RaytraceMaterial>.Color_Density_Enable Boolean default: false—animatable

Turns on/off the color density controls.

<RaytraceMaterial>.Color_Density_Start Float default: 0.0 -- animatable

The position in the object where the density color begins to appear.

<RaytraceMaterial>.Color_Density_End Float default: 25.0 -- animatable

The position in the object where the density color reaches its full Amount value.

<RaytraceMaterial>.Color_Density_Amount Float default: 1.0 -- animatable

The amount of density color. It can range from 0 to 1.0. Reducing this value reduces the density color effect.

<RaytraceMaterial>.Color_Density_Color Color default: (color 255 255 255) -- animatable

Sets a transmission color based on thickness. While filter (Transparency) color tints objects behind the transparent object, the density color gives the appearance of color within the object itself, like tinted glass.

<RaytraceMaterial>.Fog_Enable Boolean default: false—animatable

Turn on/off the use of density fog in the raytrace material.

<RaytraceMaterial>.Fog_Start Float default: 0.0 -- animatable

The position in the object where the density fog begins to appear.

<RaytraceMaterial>.Fog_End Float default: 25.0 -- animatable

The position in the object where the density fog reaches its full Amount value.

<RaytraceMaterial>.Fog_Amount Float default: 1.0 -- animatable

Controls the amount of density fog. It can range from 0 to 1.0. Reducing this value reduces the density fog effect and makes the fog translucent.

<RaytraceMaterial>.Fog_Color Color default: (color 255 255 255) -- animatable

The color of the density fog.

<RaytraceMaterial>.Reflection_Type Integer default: 0 -- animatable

Set the type of reflection:

Default (Reflections are layered with the diffuse color)

Additive (Refelections are added to the diffuse color)

<RaytraceMaterial>.Reflection_Gain Float default: 0.5 -- animatable

Controls reflection brightness. The lower the gain value, the brighter the reflection. At a gain of 1.0, no reflection is visible.

<RaytraceMaterial>.Enable_Raytraced_Reflections Boolean default: false

Turns raytracing of reflective objects on or off.

<RaytraceMaterial>.Enable_Raytraced_Refractions Boolean default: true

Turns raytracing of transparent objects on or off.

<RaytraceMaterial>.Reflection_Falloff_Mode Integer default: 0 -- animatable

When on, dims reflections to black at distance specified by Reflection_Falloff_End_Distance:

0- Off (Turns off attenuation)

1- Linear

2- Inverse Square (Inverse square is the actual attenuation rate for light in the real world.)

3- Exponential

<RaytraceMaterial>.Reflection_Falloff_End_Distance Float default: 100.0 -- animatable

The distance in world units where the reflected ray is fully attenuated.

<RaytraceMaterial>.Refraction_Falloff_Mode Integer default: 0 -- animatable

Sets the falloff mode for refraction in the raytrace material:

0- Off (Turns off attenuation)

1- Linear

2- Inverse Square (Inverse square is the actual attenuation rate for light in the real world.)

3- Exponential

<RaytraceMaterial>.Refraction_Falloff_End_Distance Float default: 100.0 -- animatable

The distance in world units where the refracted ray is fully attenuated.

<RaytraceMaterial>.Bump_Map_Effect Float default: 1.0 -- animatable

Adjusts the effect of bump maps on raytraced reflections and refractions.

<RaytraceMaterial>.Override_Global_Antialiasing_Settings Boolean default: false—animatable

If Override_Global_Antialiasing_Settings = false, Global Antialiasing Settings are used. If true, the antialiaser is determined by Adaptive_Antialiasing_On.

<RaytraceMaterial>.Adaptive_Antialiasing_On Boolean default: false—animatable

If Adaptive_Antialiasing_On = true, the Multiresolution Adaptive Antialiaser is used; otherwise the Fast Adaptive Antialiaser is used. This property only has an effect if Override_Global_Antialiasing_Settings = true.

The following properties are associated with the Options dialog

<RaytraceMaterial>.Options___Raytracer_Enable Boolean default: true -- animatable

Turns the raytracer on or off.

<RaytraceMaterial>.Options___Antialiasing_Enable Boolean default: true -- animatable

Turns antialiasing on or off.

<RaytraceMaterial>.Options___Self_Reflect_Refract Boolean default: true -- animatable

Turns self reflection/refraction on or off.

<RaytraceMaterial>.Options___Raytrace_Atmospherics Boolean default: true -- animatable

Turns the raytracing of atmospheric effects on or off. Atmospheric effects include fire, fog, volume light, and so on.

<RaytraceMaterial>.Options___Reflect_Refract_Material_ID_s Boolean default: true -- animatable

When on, the material reflects effects assigned to material IDs in the renderer's G-Buffer.

<RaytraceMaterial>.Options___Raytrace_Objects_in_Glass Boolean default: true -- animatable

Turns the raytracing of objects inside raytraced objects on or off.

<RaytraceMaterial>.Options___Raytrace_Atmospherics_in_Glass Boolean default: true -- animatable

Turns the raytracing of atmospherics inside raytraced objects on or off.

<RaytraceMaterial>.Options___Color_Density___Fog_Enable Boolean default: true -- animatable

Turns the color density and fog features on or off.

The following properties are associated with the Antialiaser configuration dialogs.

<RaytraceMaterial>.Local_Threshold Float default: 0.1 -- animatable

The sensitivity of the adaption algorithm. This value can range from 0 to 1, where 0 always casts the maximum number of rays and 1 always casts only the minimum number of rays.

<RaytraceMaterial>.Local_Min__Rays Integer default: 4 -- animatable

The minimum number of rays that the algorithm casts.

<RaytraceMaterial>.Local_Max__Rays Integer default: 32 -- animatable

The maximum number of rays the algorithm casts.

<RaytraceMaterial>.Local_Blur_Offset Float default: 0.0 -- animatable

The sharpness or blurriness of reflections or refractions without regard to distance. This value is specified in pixels.

<RaytraceMaterial>.Local_Blur_Aspect Float default: 1.0 -- animatable

Changes the shape of the blur by changing the aspect ratio.

<RaytraceMaterial>.Local_Defocus Float default: 0.0 -- animatable

Blurs based on distance. Objects near the surface are not blurred, but objects farther away are blurred. The rays cast are spread as they leave the surface of the raytrace map object.

<RaytraceMaterial>.Local_Defocus_Aspect Float default: 1.0 -- animatable

Changes the shape of the defocusing by changing the aspect ratio.

The following properties are associated with the Maps rollout.

<RaytraceMaterial>.ambientMap TextureMap default: undefined

The map assigned to the ambient map channel.

<RaytraceMaterial>.ambientMapAmount Float default: 100.0

The relative strength of the ambient map channel.

<RaytraceMaterial>.ambientMapEnable Boolean default: false

Turn on/off use of the ambient map channel.

<RaytraceMaterial>.bumpMap TextureMap default: undefined

The map assigned to the bump map channel.

<RaytraceMaterial>.bumpMapAmount Float default: 100.0

The relative strength of the bump map channel.

<RaytraceMaterial>.bumpMapEnable Boolean default: false

Turn on/off use of the bump map channel.

<RaytraceMaterial>.diffuseMap TextureMap default: undefined

The map assigned to the diffuse map channel.

<RaytraceMaterial>.diffuseMapAmount Float default: 100.0

The relative strength of the diffuse map channel.

<RaytraceMaterial>.diffuseMapEnable Boolean default: false

Turn on/off use of the diffuse map channel.

<RaytraceMaterial>.displacementMap TextureMap default: undefined

The map assigned to the displacement map channel.

<RaytraceMaterial>.displacementMapAmount Float default: 100.0

The relative strength of the displacement map channel.

<RaytraceMaterial>.displacementMapEnable Boolean default: false

Turn on/off use of the displacement map channel.

<RaytraceMaterial>.reflectionMap TextureMap default: undefined

The map assigned to the reflection map channel.

<RaytraceMaterial>.reflectionMapAmount Float default: 100.0

The relative strength of the reflection map channel.

<RaytraceMaterial>.reflectionMapEnable Boolean default: false

Turn on/off use of the reflection map channel.

<RaytraceMaterial>.refractionMap TextureMap default: undefined

The map assigned to the refraction map channel.

<RaytraceMaterial>.refractionMapAmount Float default: 100.0

The relative strength of the refraction map channel.

<RaytraceMaterial>.refractionMapEnable Boolean default: false

Turn on/off use of the refraction map channel.

<RaytraceMaterial>.glossinessMap TextureMap default: undefined

The map assigned to the glossiness map channel.

<RaytraceMaterial>. glossinessMapAmount Float default: 100.0

The relative strength of the glossiness map channel.

<RaytraceMaterial>. glossinessMapEnable Boolean default: false

Turn on/off use of the glossiness map channel.

<RaytraceMaterial>.specularLevelMap TextureMap default: undefined

The map assigned to the specularLevel map channel.

<RaytraceMaterial>.specularLevelMapAmount Float default: 100.0

The relative strength of the specularLevel map channel.

<RaytraceMaterial>.specularLevelMapEnable Boolean default: false

Turn on/off use of the specularLevel map channel.

<RaytraceMaterial>.luminosityMap TextureMap default: undefined

The map assigned to the luminosity map channel.

<RaytraceMaterial>.luminosityMapAmount Float default: 100.0

The relative strength of the luminosity map channel.

<RaytraceMaterial>.luminosityMapEnable Boolean default: false

Turn on/off use of the luminosity map channel.

<RaytraceMaterial>.transparencyMap TextureMap default: undefined

The map assigned to the transparency map channel.

<RaytraceMaterial>.transparencyMapAmount Float default: 100.0

The relative strength of the transparency map channel.

<RaytraceMaterial>.transparencyMapEnable Boolean default: false

Turn on/off use of the transparency map channel.

<RaytraceMaterial>.environmentMap TextureMap default: undefined

The map assigned to the environment map channel.

<RaytraceMaterial>.environmentMapAmount Float default: 100.0

The relative strength of the environment map channel.

<RaytraceMaterial>.environmentMapEnable Boolean default: false

Turn on/off use of the environment map channel.

<RaytraceMaterial>.transEnvMap TextureMap default: undefined

The map assigned to the transEnv map channel.

<RaytraceMaterial>.transEnvMapAmount Float default: 100.0

The relative strength of the transEnv map channel.

<RaytraceMaterial>.transEnvMapEnable Boolean default: false

Turn on/off use of the transEnv map channel.

<RaytraceMaterial>.iorMap TextureMap default: undefined

The map assigned to the ior map channel.

<RaytraceMaterial>.iorMapAmount Float default: 100.0

The relative strength of the ior map channel.

<RaytraceMaterial>.iorMapEnable Boolean default: false

Turn on/off use of the ior map channel.

<RaytraceMaterial>.translucencyMap TextureMap default: undefined

The map assigned to the translucency map channel.

<RaytraceMaterial>.translucencyMapAmount Float default: 100.0

The relative strength of the translucency map channel.

<RaytraceMaterial>.translucencyMapEnable Boolean default: false

Turn on/off use of the translucency map channel.

<RaytraceMaterial>.extraLightingMap TextureMap default: undefined

The map assigned to the extraLighting map channel.

<RaytraceMaterial>.extraLightingMapAmount Float default: 100.0

The relative strength of the extraLighting map channel.

<RaytraceMaterial>.extraLightingMapEnable Boolean default: false

Turn on/off use of the extraLighting map channel.

<RaytraceMaterial>.flourescenceMap TextureMap default: undefined

The map assigned to the flourescence map channel.

<RaytraceMaterial>.flourescenceMapAmount Float default: 100.0

The relative strength of the flourescence map channel.

<RaytraceMaterial>.flourescenceMapEnable Boolean default: false

Turn on/off use of the flourescence map channel.

<RaytraceMaterial>.colorDensityMap TextureMap default: undefined

The map assigned to the colorDensity map channel.

<RaytraceMaterial>.colorDensityMapAmount Float default: 100.0

The relative strength of the colorDensity map channel.

<RaytraceMaterial>.colorDensityMapEnable Boolean default: false

Turn on/off use of the colorDensity map channel.

<RaytraceMaterial>.fogColorMap TextureMap default: undefined

The map assigned to the fogColor map channel.

<RaytraceMaterial>.fogColorMapAmount Float default: 100.0

The relative strength of the fogColor map channel.

<RaytraceMaterial>.fogColorMapEnable Boolean default: false

Turn on/off use of the fogColor map channel.

<RaytraceMaterial>.diffusionMap TextureMap default: undefined

The map assigned to the diffusion map channel.

<RaytraceMaterial>.diffusionMapAmount Float default: 100.0

The relative strength of the diffusion map channel.

<RaytraceMaterial>.diffusionMapEnable Boolean default: false

Turn on/off use of the diffusion map channel.

<RaytraceMaterial>.specularMap TextureMap default: undefined

The map assigned to the specular color map channel.

<RaytraceMaterial>.specularMapAmount Float default: 100.0

The relative strength of the specular color map channel.

<RaytraceMaterial>.specularMapEnable Boolean default: false

Turn on/off use of the specular color map channel.

The following properties are associated with the Dynamics Properties rollout. These properties are not present in 3D Studio VIZ.

<RaytraceMaterial>.Bounce_Coefficient Float default: 1.0 -- animatable

Sets how far an object bounces after hitting a surface. The higher the value, the greater the bounce. A value of 1 represents a "perfectly elastic collision," or a bounce in which no kinetic energy is lost.

<RaytraceMaterial>.Static_Friction Float default: 0.0 -- animatable

Sets how difficult it is for the object to start moving along a surface. The higher this value, the more difficult.

<RaytraceMaterial>.Sliding_Friction Float default: 0.0 -- animatable

Sets how difficult it is for the object to keep moving over a surface. The higher this value, the more difficult for the object to keep moving.

The following properties do not correspond to any user-interface items, but appear to be used by the raytracer. These properties appear to be similar to the corresponding properties for the Raytrace TextureMap.

<RaytraceMaterial>.Attenuation_Start Float default: 0.0

The distance in world units where attenuation begins.

<RaytraceMaterial>.Attenuation_Exponent Float default: 2.0

The distance in world units where the ray is fully attenuated.

<RaytraceMaterial>.Attenuation_Color_Mode Integer default: 0

This affects the behavior of light rays as they attenuate out:

0- 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.)

1- Use Attenuation_Color

<RaytraceMaterial>.Attenuation_Color Color default: (color 0 0 0)

The color used for attenuation.

<RaytraceMaterial>.Attenuation_Near Float default: 1.0

The strength of the reflected/refracted ray at the start range distance. This is a normalized percentage that can range from 0.0 to 1.0.

<RaytraceMaterial>.Attenuation_Control_1 Float default: 0.6666

Controls the shape of the curve near the curve start.

<RaytraceMaterial>.Attenuation_Control_2 Float default: 0.3333

Controls the shape of the curve near the curve end.

<RaytraceMaterial>.Attenuation_Far Float default: 0.0

Sets the strength of the reflected/refracted ray at the end range distance. This is a normalized percentage that can range from 0.0 to 1.0.

<RaytraceMaterial>.Blur_Map Boolean default: false

When on, the software uses a map to apply the Blur Offset value. That is, where the map is white, blur offset is fully applied, and where it is black, it is ignored. For example, if the map is a Checker map, blur offset is applied only in every other square. Values between black and white cause less blur.

<RaytraceMaterial>.Defocus_Map Boolean default: false

When on, uses a map to apply the Defocus value. That is, where the map is white, Defocus is fully applied, and where it is black, it is ignored. For example, if the map is a Checker map, Defocus is applied only in every other square. Values between black and white cause less defocusing.

<RaytraceMaterial>.Enable_Reflection_Falloff Boolean default: false

Turns on/off falloff of reflection.

<RaytraceMaterial>.Reflection_Falloff_Distance Float default: 0.0

The distance until the reflections are fully attenuated.

<RaytraceMaterial>.Enable_Refraction_Falloff Boolean default: false

Turns on/off falloff of refraction.

<RaytraceMaterial>.Refraction_Falloff_Distance Float default: 0.0

The distance until the refractions are fully attenuated.

Notes

The following user-interface properties not exposed to MAXScript in 3ds max 3: Shading, 2-Sided, Wire, Face Map, and SuperSample

See also

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


StandardMaterial : Material

Constructor

standardMaterial ...

standard ...

Properties

The properties of a standard material vary based on the shader type. The following properties are applicable to all shader types:

<Standard>.shaderType Integer default: 1 -- alias: Shader_Type

Sets the shader type:

0- Anisotropic

1- Blinn

2- Metal

3- Multi-Layer

4- Oren-Nayar-Blinn

5- Phong

6- Strauss

<Standard>.shaderByName String default: "Blinn"-alias: Shader_Name

Sets the type of shader with a string, rather than a number. Enter "anisotropic", "blinn", "metal", "multi-layer", "oren-nayar-blinn", "phong", or "strauss".

Note: The .shaderType and .shaderByName are linked and will automatically change each others values.

<Standard>.wire Boolean default: false

When on, the material will be rendered in wireframe mode.

<Standard>.twoSided Boolean default: false -- alias: Two_sided

When on, the material will be applied to both sides of the selected faces.

<Standard>.faceMap Boolean default: false -- alias: Face_Map

Applies the material to the faces of the geometry. If the material is a mapped material, it requires no mapping coordinates. The map is automatically applied to each facet of the object.

<Standard>.faceted Boolean default: false

Renders each face of a surface as if it were flat.

<Standard>.adTextureLock Boolean default: false -- alias: Ambient_Diffuse_Texture_Lock

When on, ambient and diffuse texture maps will be locked.

<Standard>.adLock Boolean default: false -- alias: Ambient_Diffuse_Lock

When on, ambient and diffuse colors will be locked.

<Standard>.opacityType Integer default: 0 -- alias: Opacity_Type

Sets the type of opacity:

0- Filter

1- Subtractive

2- Additive

<Standard>.opacity Float default: 100.0 -- animatable, percentage

Sets the opacity/transparency of the material as a percentage.

<Standard>.filterColor Color default: (color 127.5 127.5 127.5) -- animatable, alias: Filter_Color

The color transmitted through transparent or semi-transparent materials such as glass.

<Standard>.opacityFallOffType Integer default: 0, -- alias: Falloff_Type

Sets the fallof type:

0- In (Increases transparency towards the inside of the object, as in a glass bottle.)

1- Out (Increases transparency towards the outside of the object, as in a cloud of smoke.)

<Standard>.opacityFallOff Float default: 0.0 -- animatable, percentage, alias: Falloff

Specifies the amount of transparency at the outside or inside extreme.

<Standard>.ior Float default: 1.5 -- animatable, alias: Index_of_Refraction

Sets the index of refraction (IOR) used by refraction maps and raytracing. The IOR controls how severely the material refracts transmitted light. Left at 1.0, the IOR of air, the object behind the transparent object does not distort. At 1.5 the object behind distorts greatly, like a glass marble. At an IOR slightly less than 1.0, the object reflects along its edges, like a bubble seen from under water.

<Standard>.wireSize Float default: 1.0 -- animatable, alias: Wire_Size

Sets the size of the wire in wireframe mode.

<Standard>.wireUnits Integer default: 0 -- alias: Wire_Units

Sets the unites to use with the .wiresize value:

0- Pixels

1- Units

<Standard>.applyReflectionDimming Boolean default: false -- alias: Apply_Reflection_Dimming

Turn on to use reflection dimming. When off, the reflection-mapped material is not affected by the presence or absence of direct light.

<Standard>.dimLevel Float default: 0.0 -- animatable, alias: Dim_Level

The amount of dimming that takes place in shadow. At 0.0, the reflection map is completely dark in shadow. At 0.5, the reflection map is half dimmed. At 1.0, the reflection map is not dimmed and the material appears as if Apply were turned off.

<Standard>.reflectionLevel Float default: 3.0 -- animatable, alias: Reflection_Level

Affects the intensity of the reflection that is not in shadow. The Reflection Level value multiplies the illumination level of the lit area of the reflection, to compensate for dimming.

<Standard>.sampler Integer default: 3 -- alias: Pixel_Sampler

Sets the sampler type:

0- 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. )

1- 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. )

2- Hammersley (Spaces samples regularly along the X axis, but along the Y axis it spaces them according to a scattered, "quasi random" pattern. Depending on Quality, the number of samples can range from 4 to 40.)

Max 2.5 Star (The sample at the center of the pixel is averaged with 4 samples surrounding it. The pattern is like the fives on dice.)
<Standard>.samplerByName String default: "Max 2.5 Star" -- alias: Sampler_Name

Sets the sampler type by name. Enter "Adaptive Halton", "Adaptive Uniform", "Hammersley", or "Max 2.5 Star".

<Standard>.samplerEnable Boolean default: false -- animatable, alias: Sampler_Enable

When on, applies supersampling to the material.

<standard>.subSampleTextureOn Boolean default: true -- alias: SubSample_Textures

When on, the maps applied to the material are supersampled as well. When off, the supersampler uses pixel averages for maps.

<Standard>.samplerQuality Float default: 0.5 -- animatable, alias: Sampler_Enable

Adjusts the quality of supersampling by controlling the number of samples used for each pixel.

<Standard>.samplerAdaptOn Boolean default: true -- alias: Adaptive_On

When on, these methods take fewer samples than the Quality specifies unless samples show a change in color greater than the Threshold value. In that case, they take all the samples specified by the Quality. Turning on Adaptive On can reduce the amount of time required to supersample.

<Standard>.samplerAdaptThreshold Float default: 0.1 -- alias: Adaptive_Threshold

Controls the Adaptive methods. A change in color greater than the Threshold value causes the adaptive methods to take the full number of samples specified by the Quality. If the color does not change as much, the adaptive method takes fewer samples and does not require as much processing time.

<Standard>.samplerAdvancedOptions Boolean default: true -- alias: Advanced_Options

The samplerAdvancedOptions property is defined as a property, but is not used by the Standard material.

<standard>.UserParam0 Float default: 0.0 -- alias: Optional_Param0

<standard>.UserParam1 Float default: 0.0 -- alias: Optional_Param1

The UserParam0 and UserParam1 properties are defined as properties, but are not used by the Standard material.

<Standard>.maps ArrayParameter default: #(undefined, undefined, ... , undefined, undefined)

<Standard>.mapEnables ArrayParameter default: #(false, false, ... , false, false) -- alias: Map_Enables

<Standard>.mapAmounts ArrayParameter default: #(100.0, 100.0, ... , 100.0, 100.0) -- animatable, alias: Map_Amounts

The three map arrays each have 24 elements and store data related to the material's maps. The maps array stores the textureMap for each channel, the mapEnables array stores whether the that map channel is enabled, and the mapAmounts array stores the amount value for each channel. The meaning of each map channel depends on the shaderType value. Table Map Channels for Standard Material Shaders shows the meaning of each map channel for each shader. For example, for the Blinn shader type element 5 of the map arrays correspond to the Glossiness map channel. The names in this table also reflect property aliases that have been defined for easier access to the map channels. Again for the Blinn shader type, array element 4, the property aliases for the 3 map arrays are: GlossinessMap (maps[5]), GlossinessMapEnable (mapEnables[5]), and GlossinessMapAmount (mapAmounts[5]). A textureMap needs to be assigned to a maps array element (or alias) before the corresponding mapAmounts property (or alias) can be animated.

The following properties are associated with the Dynamics Properties rollout. These properties are not present in 3D Studio VIZ.

<Standard>.bounce Float default: 1.0 -- animatable, alias: Bounce_Coefficient

Sets how far an object bounces after hitting a surface. The higher the value, the greater the bounce. A value of 1 represents a "perfectly elastic collision," or a bounce in which no kinetic energy is lost.

<Standard>.staticFriction Float default: 0.0 -- animatable, alias: Static_Friction

Sets how difficult it is for the object to start moving along a surface. The higher this value, the more difficult.

<Standard>.slidingFriction Float default: 0.0 -- animatable, alias: Sliding_Friction

Sets how difficult it is for the object to keep moving over a surface. The higher this value, the more difficult for the object to keep moving.

Shader Types: Phong; Metal; Blinn; Oren-Nayar-Blinn; Anisotropic

Unless otherwise noted, the following additional properties are applicable to the above shader types:

<Standard>.ambient Color default: (color 25.5 25.5 25.5) -- animatable, alias: Ambient_Color

Controls the ambient color. The ambient color is the color in direct light.

<Standard>.diffuse Color default: (color 127.5 127.5 127.5) -- animatable, alias: Diffuse_Color

Controls the diffuse color. The diffuse color is the color in direct light.

<Standard>.specular Color default: (color 229.5 229.5 229.5) -- animatable, alias: Specular_Color

Controls the specular color. The specular color is the color of the highlight on a shiny object.

<Standard>.dsLock Boolean default: false -- alias: Diffuse_Specular_Lock

When on, the diffuse and specular colors are linked together.

<Standard>.useSelfIllumColor Boolean default: false -- alias: Use_Self_Illumination

When on, the material uses a special self-illumination color (.selfIllumColor). When off, the material uses the diffuse color for self-illumination.

<Standard>.selfIllumAmount Float default: 0.0 -- animatable, percentage, alias: Self_Illumination

Sets the amount of self-illumination.

<Standard>.selfIllumColor Color default: (color 0 0 0) -- animatable, alias: Self_Illum_Color

Sets a separate color to use for self-illumination.

<Standard>.specularLevel Float default: 5.0 -- animatable, percentage, alias: Specular_Level

Affects the intensity of the specular highlight. As you increase the value, the highlight grows brighter.

<Standard>.glossiness Float default: 25.0 -- animatable, percentage

Affects the size of the specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier.

<Standard>.soften Float default: 0.1 -- animatable, alias: Soften_Level

Softens the effect of specular highlights, especially those formed by glancing light. When Specular Level is high and Glossiness is low, you can get harsh backlights on surfaces. Increase the value of Soften to mitigate this effect. At 0 there is no softening. At 1.0, the maximum amount of softening is applied.

Note: Soften is not applicable to the Anisotropic shader

The following additional properties are applicable to the Oren-Nayar-Blinn shader:

<Standard>.diffuseLevel Float default: 100.0 -- animatable, percentage, alias: Diffuse_Level

Controls the brightness of the material's diffuse component. Increasing this value increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting the specular highlight.

<Standard>.diffuseRoughness Float default: 50.0 -- animatable, percentage, alias: Diff_Roughness

Controls how quickly the diffuse component blends into the ambient component. As you increase roughness, the matte appearance of the material increases. It also grows darker and appears more flat.

The following additional properties are applicable to the Anisotropic shader:

<Standard>.diffuseLevel Float default: 100.0 -- animatable, percentage, alias: Diffuse_Level

Controls the brightness of the material's diffuse component. Increasing this value increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting the specular highlight.

<Standard>.anisotropy Float default: 50.0 -- animatable, percentage

Controls the anisotropy, or shape, of the highlight. At 0, the highlight is round. At 100, the highlight is extremely narrow.

<Standard>.orientation Float default: 0.0 -- animatable, percentage

Changes the orientation of the highlight.

<Standard>.unused Integer default: 1

the unused property is defined but not used by the shader

Shader Type: Multi-Layer

<Standard>.ambient Color default: (color 25.5 25.5 25.5) -- animatable, alias: Ambient_Color

Controls the ambient color. The ambient color is the color not in direct light.

<Standard>.diffuse Color default: (color 127.5 127.5 127.5) -- animatable, alias: Diffuse_Color

Controls the diffuse color. The diffuse color is the color in direct light.

<Standard>.useSelfIllumColor Boolean default: false -- alias: Use_Self_Illumination

When on, the material uses a special self-illumination color (.selfIllumColor). When off, the material uses the diffuse color for self-illumination.

<Standard>.selfIllumAmount Float default: 0.0 -- animatable, percentage, alias: Self_Illumination

Sets the amount of self-illumination. As you increase self-illumination, the self-illumination color takes over from the ambient color. At a setting of 100, the material shows no shaded areas, although it can show specular highlights.

<Standard>.selfIllumColor Color default: (color 0 0 0) -- animatable, alias: Self_Illum_Color

Sets an alternate color to use for self-illumination.

<Standard>.diffuseLevel Float default: 100.0 -- animatable, percentage, alias: Diffuse_Level

Controls the brightness of the material's diffuse component. Increasing this value increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting the specular highlight.

<Standard>.diffuseRoughness Float default: 0.0 -- animatable, percentage, alias: Diff_Roughness

Controls how quickly the diffuse component blends into the ambient component. As you increase roughness, the matte appearance of the material increases. It also grows darker and appears more flat.

<Standard>.specular Color default: (color 229.5 229.5 229.5) -- animatable, alias: Color_1

Controls the specular color of the first color's highlight. The specular color is the color of the highlight on a shiny surface.

<Standard>.specularLevel Float default: 5.0 -- animatable, percentage, alias: Level_1

Affects the intensity of the first color's specular highlight. As you increase the value, the highlight grows brighter.

<Standard>.glossiness Float default: 25.0 -- animatable, percentage, alias: Glossiness_1

Affects the size of the first color's specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier.

<Standard>.anisotropy Float default: 0.0 -- animatable, alias: Anisotropy_1

Controls the anisotropy, or shape, of the first color's highlight. At 0, the highlight is round. At 100, the highlight is extremely narrow.

<Standard>.orientation Float default: 0.0 -- animatable, percentage

Changes the orientation of the first color's highlight.

<Standard>.specular2 Color default: (color 229.5 229.5 229.5) -- animatable, alias: Color_2

Affects the intensity of the second color's specular highlight. As you increase the value, the highlight grows brighter.

<Standard>.specularLevel2 Float default: 0.0 -- animatable, percentage, alias: Level_2

Affects the intensity of the second color's specular highlight. As you increase the value, the highlight grows brighter.

<Standard>.glossiness2 Float default: 25.0 -- animatable, percentage, alias: Glossiness_2

Affects the size of the second color's specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier.

<Standard>.anisotropy2 Float default: 0.0 -- animatable, alias: Anisotropy_2

Controls the anisotropy, or shape, of the second color's highlight. At 0, the highlight is round. At 100, the highlight is extremely narrow.

<Standard>.orientation2 Float default: 0.0 -- animatable, percentage

Changes the orientation of the second color's highlight.

Shader Type: Strauss

<Standard>.diffuse Color default: (color 127.5 127.5 127.5) -- animatable, alias: Diffuse_Color

Controls the color of the material. This corresponds to the diffuse color you specify for other kinds of shaders. With the Strauss shader, you control only this color. The shader calculates the ambient and specular color components.

<Standard>.glossiness Float default: 25.0 -- animatable, percentage

Affects the size and intensity of the specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier.

<Standard>.metalness Float default: 0.0 -- animatable, percentage

Changes the metallic appearance of a material. Increasing the Metalness value increases the metallic appearance, with glancing as well as primary highlights. Because a metallic appearance principally depends on highlights, the Metalness value has little effect unless you also increase the Glossiness value.

See also

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Map Channels for Standard Material Shaders
 | Anisotropic | Blinn | Metal | Multi-Layer | Oren-Nayar-Blinn | Phong | Strauss
1 | AmbientMap | AmbientMap | AmbientMap | AmbientMap | AmbientMap | AmbientMap | DiffuseMap
2 | DiffuseMap | DiffuseMap | DiffuseMap | DiffuseMap | DiffuseMap | DiffuseMap | GlossinessMap
3 | SpecularMap | SpecularMap | SpecularMap | DiffuseLevelMap | SpecularMap | SpecularMap | MetalnessMap
4 | DiffuseLevelMap | SpecularLevelMap | SpecularLevelMap | DiffuseRoughnessMap | GlossinessMap | SpecularLevelMap | OpacityMap
5 | SpecularLevelMap | GlossinessMap | GlossinessMap | SpecularMap | SpecularLevelMap | GlossinessMap | FilterMap
6 | GlossinessMap | SelfIllumMap | SelfIllumMap | SpecularLevelMap | SelfIllumMap | SelfIllumMap | BumpMap
7 | AnisotropyMap | OpacityMap | OpacityMap | GlossinessMap | OpacityMap | OpacityMap | ReflectionMap
8 | OrientationMap | FilterMap | FilterMap | AnisotropyMap | FilterMap | FilterMap | RefractionMap
9 | SelfIllumMap | BumpMap | BumpMap | OrientationMap | DiffuseLevelMap | BumpMap | DisplacementMap
10 | OpacityMap | ReflectionMap | ReflectionMap | specularMap2 | DiffuseRoughnessMap | ReflectionMap |
11 | FilterMap | RefractionMap | RefractionMap | SpecularLevelMap2 | BumpMap | RefractionMap |
12 | BumpMap | DisplacementMap | DisplacementMap | GlossinessMap2 | ReflectionMap | DisplacementMap |
13 | ReflectionMap |  |  | AnisotropyMap2 | RefractionMap |  |
14 | RefractionMap |  |  | OrientationMap2 | DisplacementMap |  |
15 | DisplacementMap |  |  | SelfIllumMap |  |  |
16 |  |  |  | OpacityMap |  |  |
17 |  |  |  | FilterMap |  |  |
18 |  |  |  | BumpMap |  |  |
19 |  |  |  | ReflectionMap |  |  |
20 |  |  |  | RefractionMap |  |  |
21 |  |  |  | DisplacementMap |  |  |


Shellac : Material

Constructor

Shellac ...

Properties

<Shellac>.shellacMtl1 Material default: Standard -- alias: Base_Material

The base sub-material.

<Shellac>.shellacMtl2 Material default: Standard -- alias: Shellac_Material

The shellac material.

<Shellac>.shellacColorBlend Float default: 0.0 -- animatable, percentage, alias: Shellac_Color_Blend

Controls the amount of color mixing. At 0.0, the shellac material has no effect. Increasing the Shellac Color Blend value increases the amount of shellac material color blended into the base material color. There is no upper limit on this parameter. Large values "overload" the shellac material colors.

See also

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


TopBottom : Material

Constructor

topBottom ...

topBottomMat ...

Properties

<TopBottom>.topMaterial Material default: Standard -- alias: Top______Standard

The top material.

<TopBottom>.bottomMaterial Material default: Standard -- alias: Bottom______Standard

The bottom material.

<TopBottom>.map1Enabled Boolean default: true -- alias: Map_1_Enable

Turns on/off the use of the top material in the topbottom material.

<TopBottom>.map2Enabled Boolean default: true -- alias: Map_2_Enable

Turns on/off the use of the bottom material in the topbottom material.

<TopBottom>.blend Float default: 0.0 -- animatable

Blends the edge between the top and bottom sub-materials. This is a percentage that can range from 0 to 100. At 0, there is a sharp line between the top and bottom sub-materials. At 100, the top and bottom sub-materials tint each other.

<TopBottom>.position Float default: 50.0 -- animatable

Determines where the division between the two materials lies on an object. This is a percentage that can range from 0 to 100. 0 is at the bottom of the object, and displays only the top material. 100 is at the top of the object, and displays only the bottom material.

<TopBottom>.coordinates Integer default: 0

Choose how the software determines the boundary between top and bottom:

0- 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.)

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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 TextureMap Types.

The properties, operators, and methods that are common to all classes derived directly from the TextureMap class are described in TextureMap Common Properties, Operators, and Methods.

TextureMaps also share a set of classes for properties that are used in several different TextureMap classes. These shared classes are described in TextureMap Shared Classes.

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 Material Common Properties, Operators, and Methods.


TextureMap Common Properties, Operators, and Methods

Properties

<TextureMap>.name

All the TextureMap subclasses can access the name property and specify it as a constructor parameter.

Methods

assignNewName <TextureMap>

Modifies the name of the specified texture to make it unique. The name is of the form "Map #1" where the number is incremented as required to make ensure it's unique.

renderMap <TextureMap> [ into:<bitmap> ] \

[ size:<point2> ] \

[ filename:<string> ] \

[ scale:<float> ] \

[ filter:<boolean> ] \

[ display:<boolean> ]

Provides access the Render Map function available in the Material Editor. The function returns a Bitmap value containing a rendering of the given texture map. If you specify the optional into: argument, the function renders the map into the supplied bitmap, taking size and other attributes from the existing bitmap. If you don't, a new bitmap value is created using the size: and fileName: arguments in its creation. Default size value is [200,200].

The scale: argument is a scale factor applied to 3D TextureMaps. This is the scale of the surface in 3d space that is mapped to UV and controls how much of the texture appears in the bitmap representation. Default scale value is 1.

If the filter: argument is true, the bitmap is filtered. It is quite a bit slower to rescale bitmaps with filtering on. Defaults filter value is false/off.

If the display: argument is true, the resulting bitmap is displayed using the virtual frame buffer; otherwise it is not. Default display value is false/off.

Example:

rm = renderMap $foo.material.diffuseMap size:[640,480] \

fileName:"foodif.bmp"

save rm

close rm

The above will render a map to a bitmap and save it as a .bmp file.

Associated Methods

showTextureMap <material> <TextureMap> <boolean>

This method provides control over the visibility of textures in the shaded viewport. You specify the material containing the texture map, the texture map in that material to be controlled, and a boolean to turn the display on or off. For example:

showTextureMap $foo.material $foo.material.diffuseMap on

tm = checker()

mat = standardMaterial diffuseMap:tm

mm = multimaterial()

mm[1] = mat

$box01.material = mm

showTextureMap mm[1] tm on

Note that for multimaterials, you need to specify the appropriate sub-material (using [] indexing, for example).

See also

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

StandardXYZGen

TexOutputClass


UVGenClass : Material

Properties

<textureMap.coordinates>.mappingType Integer default: 0

mappingType = 0 - Texture; 1 - Environment

If the Coordinates rollout for the textureMap is displayed in Material Editor and this property's value is changed, the Texture/Environ radiobutton and Mapping dropdown displays are not updated to reflect the change.

<textureMap.coordinates>.mapping Integer default: varies

If mapping type is Texture mapping (mappingType = 0), the default value for this property is 0. mapping = 0 – Explicit Map Channel; 1 – Vertex Color Channel; 2 – Planar from Object XYZ; 3 – Planar from World XYZ

If mapping type is Environment mapping (mappingType = 1), the default value for this property is 4. mapping = 0 - Spherical; 1 - Cylindrical; 2 - Shrink-Wrap; 3 – Screen

The mapping source for Texture and Environment mapping types are internally stored in separate variables, and the mapping source set for a mapping type is retained if you change the mapping source for the other mapping type.

<textureMap.coordinates>.mapChannel Integer default: 1

The UV coordinate map channel.

<textureMap.coordinates>.U_Offset Float default: 0.0 -- animatable

<textureMap.coordinates>.V_Offset Float default: 0.0 -- animatable

Offset mapping coordinates along the surface's local U axis or V axis. That is, at 0.0 (the default), the map begins at the U or V origin. Increasing an Offset value moves the map forward along that axis, and decreasing it moves it backward.

<textureMap.coordinates>.U_Tiling Float default: 1.0 -- animatable

<textureMap.coordinates>.V_Tiling Float default: 1.0 -- animatable

The tiling of UV mapping coordinates; that is, the number of times a mapped material's map is repeated in the surface's local U axis or V axis.

<textureMap.coordinates>.U_Angle Float default: 0.0 -- animatable, angle

Rotates the map about the U-axis (in degrees).

<textureMap.coordinates>.V_Angle Float default: 0.0 -- animatable, angle

Rotates the map about the V-axis (in degrees).

<textureMap.coordinates>.W_Angle Float default: 0.0 -- animatable, angle

Rotates the map about the W-axis (in degrees).

<textureMap.coordinates>.Blur Float default: 1.0 -- animatable

Affects the sharpness or blurriness of the map based on its distance from the view. The farther away the map is, the greater the blurring. The Blur value blurs maps in world space.

<textureMap.coordinates>.Blur_Offset Float default: 0.0 -- animatable

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

<textureMap.coordinates>.Phase Float default: 0.0 -- animatable

The speed of the animation of the noise function.

<textureMap.coordinates>.Noise_Amount Float default: 1.0 -- animatable

The strength of the fractal function, expressed as a percentage. If the amount is 0 there is no noise. If the amount is 100 the map becomes pure noise.

<textureMap.coordinates>.Noise_Levels Integer default: 1 -- animatable

The number of times the function is applied. The effect of the level is dependent on the Amount value. The stronger the amount, the greater the effect of increasing the Levels value.

<textureMap.coordinates>.Noise_Size Float default: 1.0 -- animatable

The scale of the noise function relative to geometry. At very small values, the noise effect becomes white noise. At large values, the scale can exceed the scale of the geometry, in which case it has little or no effect.

Notes

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

Value Common Properties, Operators, and Methods


StandardXYZGen : Material

Properties

<textureMap.coords>.coordType Integer default: 0

The type of coordinates used for mapping:

0- Object XYZ (Uses planar mapping based on the object's local coordinates (disregarding the pivot point location).)

1- World XYZ (Uses planar mapping based on the scene's world coordinates (disregarding the object's bounding box).)

2- Explicit Map Channel (Uses the map channel specified by the .mapChannel value.)

3- Vertex Color Channel (Uses assigned vertex colors as a channel.)

<textureMap.coords>.mapChannel Integer default: 1

The map channel used for mapping coordinates.

<textureMap.coords>.offset Point3 default: [0,0,0] -- animatable

Changes the position of the map in UV coordinates. The map moves in relation to its size.

<textureMap.coords>.Tiling Point3 default: [1,1,1] -- animatable

The number of times the map is tiled across each axis.

<textureMap.coords>.angle Point3 default: [0,0,0] -- animatable, point3 angle

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

<textureMap.coords>.blur Float default: 1.0 -- animatable

Affects the sharpness or blurriness of the map based on its distance from the view. The farther away the map is, the greater the blurring. The Blur value blurs maps in world space.

<textureMap.coords>.Blur_Offset Float default: 0.0 -- animatable

Affects the sharpness or blurriness of the map without regard to its distance from the view. Blur Offset blurs the image itself in object space.

See also

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


TexOutputClass : Material

Properties

<texturemap.output>.Output_Amount Float default: 1.0 -- animatable

The amount of the map being mixed into a composite material. Affects the saturation and alpha value of the map.

<texturemap.output>.RGB_Offset Float default: 0.0 -- animatable

This value is added to the RGB values of the map colors, which affects the tonal value of the colors. Eventually the map becomes white and self-illuminated. Lowering the value decreases the tonal value towards black.

<texturemap.output>.RGB_Level Float default: 1.0 -- animatable

The RGB values of the map colors are multiplied by this value, which affects the saturation of the color. Eventually the map becomes fully saturated and self-illuminated. Lowering the value decreases the saturation and makes the map colors grayer.

<texturemap.output>.Bump_Amount Float default: 1.0 -- animatable

Adjusts the amount of bumpiness. This value has an effect only when the map is used as a bump map.

<texturemap.output>.Mono_Color_Map subAnim

The Mono_Color_Map SubAnim contains the monochrome color mapping curve. You cannot create this curve in MAXScript, or access this curve unless you first turn on the Enable Color Map checkbox in the user interface.

<texturemap.output>.RGB_Color_Map subAnim

The RGB_Color_Map SubAnim contains the RGB color mapping curves. You cannot create these curves in MAXScript, or access the curves unless you first turn on the Enable Color Map checkbox and select the RGB radiobutton in the user interface.

<texturemap.output.Mono_Color_Map>.curve_1 SubAnim

The curve_1 SubAnim contains the monochrome color mapping curve points. You cannot create or access these points unless the point is animated. If a point is animated, you can access the point position using the .Point_X property of curve_1, where X in the point number.

<texturemap.output.RGB_Color_Map>.curve_1 SubAnim

<texturemap.output.RGB_Color_Map>.curve_2 SubAnim

<texturemap.output.RGB_Color_Map>.curve_3 SubAnim

The curve_1, curve_2, and curve_3 SubAnims contains the R, G, and B color mapping curve, respectively. You cannot create or access points in these curves unless the point is animated. If a point is animated, you can access the point position using the .Point_X property of the curve, where X in the point number.

Notes

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

Value Common Properties, Operators, and Methods


TextureMap Types

The following list displays the 3ds max TextureMap subclasses:

Adobe_Photoshop_Plug_In_Filter

Adobe_Premiere_Video_Filter

Bitmap

Bricks

Cellular

Checker

Composite

Dent

Falloff

FalloffTextureMap

FlatMirror

Gradient

Gradient_Ramp

Marble

Mask

Mix

Noise

NoTexture

Output

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


Adobe_Photoshop_Plug_In_Filter : TextureMap

Constructor

adobe_photoshop_plug_in_filter ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Adobe_Photoshop_Plug_In_Filter>.blur Float default: 0.0 -- animatable, percentage

<Adobe_Photoshop_Plug_In_Filter>.Foreground_Color Color default: (color 0 0 0) -- animatable

Specifies the foreground color for the image, used by some Photoshop filters.

<Adobe_Photoshop_Plug_In_Filter>.Background_Color Color default: (color 0 0 0) -- animatable

Specifies the background color for the image, used by some Photoshop filters.

<Adobe_Photoshop_Plug_In_Filter>.coordinates SubAnim

See UVGenClass for the StandardUVGen properties.

<Adobe_Photoshop_Plug_In_Filter>.output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties.

Notes

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

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Adobe_Premiere_Video_Filter : TextureMap

Constructor

adobe_premiere_video_filter ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Adobe_Premiere_Video_Filter>.coordinates SubAnim

See UVGenClass for the StandardUVGen properties.

<Adobe_Premiere_Video_Filter>.output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties.

Notes

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

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


BitmapTexture : TextureMap

Constructor

bitmaptexture ...

bitmaptex ...

Properties

<Bitmaptexture>.bitmap Bitmap default: Bitmap:

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.

<Bitmaptexture>.filename String default: "" -- alias: file_name

The name of the bitmap file.

<Bitmaptexture>.filtering Integer default: 0

The method of pixel averaging used in antialiasing the bitmap:

0- Pyramidal (Requires less memory and is adequate for most purposes.)

1- Summed Area (Requires much more memory, but yields generally superior results.)

2- None (Turns off filtering.)

<Bitmaptexture>.monoOutput Integer default: 0

Some parameters, such as opacity or specular level are a single value as opposed to a material's three-value color components. Controls in this group determine the source of the Output mono channel in terms of the input bitmap:

0- 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).)

1- Alpha (Uses the intensity of the alpha channel for mapping.)

<Bitmaptexture>.RGBOutput Integer default: 0

The RGB Channel Output determines where the output RGB part comes from. The controls in this group affect only maps for material components that display color: Ambient, Diffuse, Specular, Filter Color, Reflection, and Refraction.

0- RGB (Displays the full color values of the pixels.)

1- Alpha as Gray (Displays tones of gray based on the levels of the alpha channel.)

<Bitmaptexture>.apply Boolean default: false

Turn on to use the cropping or placements settings.

<Bitmaptexture>.cropPlace Integer default: 0

Set whether cropping or placement is active:

0- Crop

1- Place

<Bitmaptexture>.clipu Float default: 0.0 -- animatable, alias: clip_u_offset

Adjusts the bitmap location along the U-axis.

<Bitmaptexture>.clipv Float default: 0.0 -- animatable, alias: clip_v_offset

Adjusts the bitmap location along the V-axis.

<Bitmaptexture>.clipw Float default: 1.0 -- animatable, alias: clip_u_width

Adjusts the width of the bitmap.

<Bitmaptexture>.cliph Float default: 1.0 -- animatable, alias: clip_v_width

Adjusts the height of the bitmap.

<Bitmaptexture>.jitter Float default: 1.0 -- animatable, alias: jitter_placement

The amount of random offset. At 0, there is no random offset.

<BitmapTex>.useJitter BooleanClass default: false -- boolean

Apply the .jitter value.

<Bitmaptexture>.alphasource Integer default: 0

Controls in this group determine the source of the Output alpha channel in terms of the input bitmap:

0- Image Alpha (Uses the image's alpha channel.)

1- RGB Intensity (Converts the colors in the bitmap to grayscale tonal values and uses them for transparency. Black is transparent and white is opaque.)

2- None (Opaque; does not use transparency.)

<Bitmaptexture>.preMultAlpha Boolean default: true

Determines how alpha is treated in the bitmap. When turned on, the default, premultiplied alpha is expected in the file. When turned off, the alpha is treated as non-premultiplied, and any RGB values are ignored.

<Bitmaptexture>.starttime Time default: 0f

The frame where the playback of the animated map will begin.

<Bitmaptexture>.playbackrate Float default: 1.0

Lets you speed up and slow down the rate that the animation is applied to the map (for example, 1.0 is normal speed, 2.0 is twice as fast, .333 is 1/3 as fast).

<Bitmaptexture>.endcondition Integer default: 0

These controls determine what happens after the last frame of the animation:

0- Loop (Causes the animation to loop over and over again.)

1- Ping Pong (Causes the animation to be played backwards, making every animated sequence "loop smoothly.")

2- Hold (Causes the last frame of the animation to be frozen on the surface until the end of the scene.)

<Bitmaptexture>.coords StandardUVGen -- alias: coordinates

See UVGenClass for the StandardUVGen properties.

<Bitmaptexture>.output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties.

Associated Methods

enumerateFiles [ <MAXWrapper_obj> ] <function> [ <arg> ] \

[ #inactive ] [ #videoPost ] [ #render ] [ #missing ] \

[ #localOnly ]

Lets you run through all the bitmap files currently used in the scene or in an individual object. You can filter this so it just gives you the bitmap files that are inactive or missing.

See Bitmap Files 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

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Bricks : TextureMap

Constructor

bricks ...

Properties

<Bricks>.Brick_Type Integer default: 1

Brick_Type = 0 - Custom Bricks; 1 - Running Bond; 2 - Common Flemish Bond; 3 - English Bond; 4 - ½ Running Bond; 5 - Stack Bond; 6 - Fine Running Bond; 7 - Fine Stack Bond

The brick_type values define a set of predefined values for the Stacking and Row and Column Editing properties. Changing brick_type only updates these properties if Material Editor is displayed and the material is in the active slot.

<Bricks>.Show_Texture_Swatches Integer default: 1

When on, updates to show the texture assigned by a map for Bricks or Mortar.

0- Off

1- On

<Bricks>.Brick_Color Color default: (color 165.75 76.5 51) -- animatable

The color of the bricks.

<Bricks>.Horizontal_Count Float default: 3.0 -- animatable

The number of bricks in a row.

<Bricks>.Vertical_Count Float default: 8.0 -- animatable

The number of bricks in a column.

<Bricks>.Color_Variance Float default: 0.4 -- animatable

The color variation among the bricks.

<Bricks>.Fade_Variance Float default: 0.2 -- animatable

The fading variation among the bricks.

<Bricks>.Mortar_Color Color default: (color 211.65 196.35 183.6) -- animatable

The color of the mortar.

<Bricks>.Horizontal_Gap Float default: 1.0 -- animatable

The horizontal size of the mortar between the bricks.

<Bricks>.Vertical_Gap Float default: 1.0 -- animatable

The vertical size of the mortar between the bricks.

<Bricks>.Lock_Gap_Symmetry Integer default: 1

When on, the vertical_gap and horizontal_gap values are locked to one another.

0- Off

1- On

<Bricks>.Holes Integer default: 0 -- animatable

The percentage of holes in the bricked surface caused by missing bricks. The mortar shows through the holes.

<Bricks>.Edge_Roughness Float default: 0.0 -- animatable

Controls the roughness of the edges of the mortar.

<Bricks>.Random_Seed Integer default: 43304 -- animatable

Randomly applies patterns of color variation to the bricks. Does not require any other setting to generate completely different patterns.

<Bricks>.Line_Shift Float default: 0.0 -- animatable

Shifts every second row of bricks a distance of one unit.

<Bricks>.Random_Shift Float default: 0.0 -- animatable

Randomly shifts all rows of bricks a distance of one unit.

<Bricks>.Use_Row_Edit Integer default: 0

Turn on/off row edit:

0- Off

1- On

<Bricks>.Per_Row Integer default: 2

The amount of bricks per row.

<Bricks>.Change_Row Float default: 1.0

For every row you specify in the Per_Row value, the software stores the amount of bricks that you specify in the Change_row value.

<Bricks>.Use_Column_Edit Integer default: 0

Turn on/off column edit:

0- Off

1- On

<Bricks>.Per_Column Float default: 1.0

The amount of bricks per column.

<Bricks>.Change_Column Float default: 1.0

For every row you specify in the Per_Column value, the software stores the amount of bricks that you specify in the Change_column value.

<Bricks>.coords SubAnim

See UVGenClass for the StandardUVGen properties.

Notes

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 Per_Column property.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Cellular : TextureMap

Constructor

cellular ...

Properties

<Cellular>.celcolor Color default: (color 255 255 255) -- animatable, alias: Cell_Color

The color of the cell.

<Cellular>.cellmap textureMap default: undefined

Assigns a map to the cells, rather than a solid color.

<Cellular>.map1Enabled Boolean default: true -- alias: Map1_On

When on, enables the map. When off, disables the map (cell color reverts to celcolor).

<Cellular>.variation Float default: 0.0 -- animatable

Varies the color of the cells by randomly altering RGB values. The higher the variation, the greater the random effect. This percentage value can range from 0 to 100. At 0, the color swatch or the map completely determines the cell color.

<Cellular>.divcolor1 Color default: (color 127.5 127.5 127.5) -- animatable, alias: Division_Color1

The color of the first cell division.

<Cellular>.divmap1 textureMap default: undefined -- alias: DivisionMap1

Assigns a map to the first cell division.

<Cellular>.map2Enabled Boolean default: true -- alias: Map2_On

When on, enables the first cell division map. When off, disables the associated map (the division color reverts to divcolor1).

<Cellular>.divcolor2 Color default: (color 0 0 0) -- animatable, alias: Division_Color2

The color of the second cell division.

<Cellular>.divmap2 textureMap default: undefined -- alias: DivisionMap2

Assigns a map to the second cell division.

<Cellular>.map3Enabled Boolean default: true -- alias: Map3_On

When on, enables the second cell division map. When off, disables the associated map (the division color reverts to divcolor2).

<Cellular>.type Integer default: 0

Sets the shape and size of the cells:

0- Circular (This gives a more organic, or bubbly look.)

1- Chips (With Chips, the cells have linear edges. This gives a more chipped or mosaic appearance.)

<Cellular>.size Float default: 5.0 -- animatable

Alters the overall scale of the map. Adjust this value to fit the map to your geometry.

<Cellular>.spread Float default: 0.5 -- animatable

Alters the size of individual cells.

<Cellular>.smooth Float default: 0.1 -- animatable, alias: Bump_smoothing

When you use a cellular map as a bump map, you might encounter aliasing or jagginess at the boundaries of the cells. If this occurs, increase this value.

<Cellular>.fractal Boolean default: false

When on, makes the cellular pattern a fractal pattern.

<Cellular>.iteration Float default: 3.0 -- animatable, alias: Iterations

Sets the number of times the fractal function is applied. Caution: Increasing this value increases rendering time.

<Cellular>.adaptive Boolean default: true

When on, the number of fractal iterations is set adaptively. That is, the number of iterations increases the closer the geometry is to the scene's point of view, and decreases in the distance. This reduces aliasing and also saves time while rendering.

<Cellular>.roughness Float default: 0.0 -- animatable

When you use the Cellular map as a bump map, this parameter controls how rough the bumps are. When Roughness is zero, each iteration is half the strength of the previous iteration, and half the size. As Roughness increases, each iteration is closer in strength and size to the previous iteration. When Roughness is at its maximum value of 1.0, each iteration is the same size and strength as the previous. In effect, this turns off the fractalization. Roughness has no effect unless Iterations is greater than 1.0.

<Cellular>.lowthresh Float default: 0.0 -- animatable, alias: Low

<Cellular>.midthresh Float default: 0.5 -- animatable, alias: Mid

<Cellular>.highthresh Float default: 1.0 -- animatable, alias: High

These controls affect the relative size of cells and divisions. They are expressed as normalized percentages (0 to 1) of the sizes specified by the default algorithm.

lowthresh: Adjusts the size of the cells. Default=0.0.

midthresh: Adjusts the size of the first division color, relative to the second. Default=0.5.

highthresh: Adjusts the overall size of divisions. Default=1.0.

<Cellular>.coords StandardXYZGen -- alias: coordinates

See StandardXYZGen for the StandardXYZGen properties.

<Cellular>.output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Checker : TextureMap

Constructor

checker ...

Properties

<Checker>.soften Float default: 0.0 -- animatable

Blurs the edges between the checkers. A little blurs a lot.

<Checker>.color1 Color default: (color 0 0 0) -- animatable, alias: Color_1

Sets the color of one of the checkers.

<Checker>.map1 textureMap default: undefined -- alias: Map_1

Selects a map to use within the area of the checker color. For example, you could put an additional checkerboard within one of the checker colors.

<Checker>.map1Enabled Boolean default: true -- alias: Map_1_Enable

This enables the associated map.

<Checker>.color2 Color default: (color 255 255 255) -- animatable, alias: Color_2

Sets the color of the second checker.

<Checker>.map2 textureMap default: undefined -- alias: Map_2

Selects a map to use within the area of the checker color. For example, you could put an additional checkerboard within one of the checker colors.

<Checker>.map2Enabled Boolean default: true -- alias: Map_2_Enable

This enables the associated map.

<Checker>.coords StandardUVGen -- alias: coordinates

See UVGenClass for the StandardUVGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


CompositeTextureMap : TextureMap

Constructor

compositeTextureMap ...

compositeTexture ...

Properties

<CompositeTexturemap>.mapList ArrayParameter default: #(undefined, undefined) -- alias: Maps

<CompositeTexturemap>.mapEnabled ArrayParameter default: #(true, true) -- alias: Map_1_Enable

Notes

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

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Dent : TextureMap

Constructor

dent ...

Properties

<Dent>.size Float default: 200.0 -- animatable

Sets the relative size of dents. As the size increases, the number of dents decreases when other settings are the same.

<Dent>.strength Float default: 20.0 -- animatable

Higher values increase the number of dents, lower values decrease the number of dents. Decreasing Strength reduces the number of dents over a surface. At 0, the surface is smooth (no dents). Increasing Strength increases the number of dents over a surface. 100 is maximum.

<Dent>.iterations Integer default: 2 -- animatable

Sets the number of calculations used to create the dents.

<Dent>.color1 Color default: (color 0 0 0) -- animatable, alias: Color_1

Sets the color of the dent.

<Dent>.map1 TextureMap default: undefined

Colors can be replaced by maps in the dent pattern.

<Dent>.map1Enabled Boolean default: true -- alias: MapOn1

Enables the associated map.

<Dent>.color2 Color default: (color 255 255 255) -- animatable, alias: Color_2

Sets the second color of the dent.

<Dent>.map2 TextureMap default: undefined

Assigns second map to the dent pattern.

<Dent>.map2Enabled Boolean default: true -- alias: MapOn2

Enables the associated map.

<Dent>.coords StandardXYZGen -- alias: coordinates

See StandardXYZGen for the StandardXYZGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Falloff : TextureMap

Constructor

falloff ...

Properties

<Falloff>.color1 Color default: (color 0 0 0) -- animatable, alias: Color_1

Sets the first color for falloff.

<Falloff>.map1Amount Float default: 100.0 -- animatable, alias: Map_Amount_1

Relative strength of the first color in the falloff map.

<Falloff>.map1 TextureMap default: undefined -- alias: Map_1

Assigns a map to the first slot in the falloff.

<Falloff>.map1On Boolean default: true -- alias: Map_1_Enable

When on, the selected maps are used in the falloff. When off, colors are used.

<Falloff>.color2 Color default: (color 255 255 255) -- animatable, alias: Color_2

Sets the second color for falloff.

<Falloff>.map2Amount Float default: 100.0 -- animatable, alias: Map_Amount_2

Relative strength of the second color in the falloff map.

<Falloff>.map2 TextureMap default: undefined -- alias: Map_1

Assigns a map to the second slot in the falloff.

<Falloff>.map2On Boolean default: true -- alias: Map_2_Enable

When on, the selected maps are used in the falloff. When off, colors are used.

<Falloff>.type Integer default: 1 -- animatable, alias: Falloff_Type

Sets the type of falloff:

0- 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.)

1- 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.)

2- 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.)

3- Lit/Shadowed (Adjusts between two subtextures based on how much light is falling on the object.)

4- Distance Blend (Adjusts between two subtextures based on Near Distance and Far Distance values. Uses include reducing aliasing on large terrain objects and controlling the shading in non-photorealistic environments.)

<Falloff>.mtlIOROverride Boolean default: true -- alias: Mtl_IOR_Override_Enable

When on, allows change to the Index of Refraction set by the material.

<Falloff>.ior Float default: 1.6 -- animatable, alias: Index_of_Refraction

Sets a new Index of Refraction.

<Falloff>.nearDistance Float default: 0.0 -- animatable, alias: Near_Distance

The distance at which the blend effect begins.

Note: This is only available for the Distance Blend falloff type.

<Falloff>.farDistance Float default: 100.0 -- animatable, alias: Far_Distance

The distance at which the blend effect ends.

Note: This is only available for the Distance Blend falloff type.

<Falloff>.extrapolateOn Boolean default: false -- alias: Distance_Blend_Extrapolate

When on, allows the effect to continue beyond the Near and Far settings.

Note: This is only available for the Distance Blend falloff type.

<Falloff>.direction Integer default: 0 -- animatable, alias: Falloff_Direction

Sets the direction of the falloff:

0- Viewing Direction (Sets the falloff direction relative to the camera (or screen). Changing object orientation doesn't affect the falloff map.)

1- 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.)

2- 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.)

3- 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.)

4- 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.)

5- World X Axis (Sets the falloff direction to the world coordinate system X-axis. Changing object orientation doesn't affect the falloff map.)

6- World Y Axis (Sets the falloff direction to the world coordinate system Y-axis. Changing object orientation doesn't affect the falloff map.)

7- World Z Axis (Sets the falloff direction to the world coordinate system Z-axis. Changing object orientation doesn't affect the falloff map.)

<Falloff>.node Node default: undefined -- alias: Falloff_Direction_Object

When Falloff_Direction = 1, this object will determine the falloff direction.

<Falloff>.texture_output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties.

<Falloff>.mixcurve SubAnim default: SubAnim:MixCurve

This mix curve determines the falloff.

<Falloff.mixcurve>.curve_1 SubAnim default: SubAnim:Curve_1

The curve_1 SubAnim contains the mix curve points. You cannot create or access these points unless the point is animated. If a point is animated, you can access the point position using the .Point_X property of curve_1, where X in the point number.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


FlatMirror : TextureMap

Constructor

flatMirror ...

Properties

<FlatMirror>.applyBlur Boolean default: true

Turns on filtering to blur the maps. Antialiasing is also applied to the Distortion effect, if any, when Apply Blur is turned on.

<FlatMirror>.blurAmount Float default: 1.0 -- animatable

Affects the sharpness or blurriness of the generated map based on its distance from the object. The farther away the map is, the greater the blurring.

<FlatMirror>.frame Integer default: 1

When this is set to 0, the renderer creates the automatic flat mirror only on the first frame. When this is set to 1, the renderer creates the automatic flat mirror based on nthframe.

<FlatMirror>.nthFrame Integer default: 1

<FlatMirror>.useEnviroment Boolean default: true

When off, environment maps are ignored by the mirror during rendering. It's useful to turn this off when you have mirrors in the scene and you're rotoscoping against a flat screen environment map. A screen environment map does not exist in 3D space the way the other environment-map types do, and will not render properly.

<FlatMirror>.applyToFaceID Boolean default: false

When on, a specified material is applied to the mirror face.

<FlatMirror>.faceID Integer default: 1

Specifies the material ID number where you want the mirror assigned.

<FlatMirror>.distortionType Integer default: 0

To simulate irregular surfaces, you can distort the flat-mirror reflections. Distortion can be based on a bump map or on noise controls built into Flat Mirror material.

0- None (No distortion)

1- 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.)

2- Use Built-in Noise (Distorts the reflection using the settings in the Noise group.)

<FlatMirror>.noiseType Integer default: 0

Sets the type of noise when distortionType is set to 2.

0- 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.)

1- Fractal (Generates noise using a fractal algorithm. The Levels setting determines the number of iterations for the fractal noise.)

2- Turbulence (Generates fractal noise with an absolute value function applied to it to make fault lines.)

<FlatMirror>.distortionAmount Float default: 0.5 -- animatable

Adjusts the amount of distortion to the reflected image. This is the only value that affects the amount of distortion.

<FlatMirror>.phase Float default: 0.0 -- animatable

Controls the speed of the animation of the noise function. A 3D noise function is used for the noise, so that the first two parameters are U and V and the third is phase.

<FlatMirror>.size Float default: 10.0 -- animatable

Sets the scale of the noise function. Smaller values give smaller chunks of noise.

<FlatMirror>.level Float default: 2.0 -- animatable

Sets the number of fractal iterations or turbulence (as a continuous function).

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Gradient : TextureMap

Constructor

gradient ...

Properties

<Gradient>.color1 Color default: (color 0 0 0) -- animatable, alias: Color_1

The gradient interpolates between 3 colors. This is the first color.

<Gradient>.map1 TextureMap default: undefined -- alias: Map_1

You can interpolate between 3 maps instead of colors. This is the first map.

<Gradient>.map1Enabled Boolean default: true -- alias: Map_1_Enable

When on, the associated map is enabled.

<Gradient>.color2 Color default: (color 127.5 127.5 127.5) -- animatable, alias: Color_2

The gradient interpolates between 3 colors. This is the second color.

<Gradient>.map2 TextureMap default: undefined -- alias: Map_2

You can interpolate between 3 maps instead of colors. This is the second map.

<Gradient>.map2Enabled Boolean default: true -- alias: Map_2_Enable

When on, the associated map is enabled.

<Gradient>.color3 Color default: (color 255 255 255) -- animatable, alias: Color_3

The gradient interpolates between 3 colors. This is the third color.

<Gradient>.map3 TextureMap default: undefined -- alias: Map_3

You can interpolate between 3 maps instead of colors. This is the third map.

<Gradient>.map3Enabled Boolean default: true -- alias: Map_3_Enable

When on, the associated map is enabled.

<Gradient>.color2Pos Float default: 0.5 -- animatable, alias: Color_2_Position

Controls the centerpoint of the middle color. The position ranges from 0 to 1. When it is 0, color2 replaces color3. When it is 1, color2 replaces color1.

<Gradient>.gradientType Integer default: 0 -- alias: Gradient_Type

Sets the type of gradient:

0- Linear (Interpolates the color based on the vertical position.)

1- Radial (Interpolates based on the distance from the center of the map.)

<Gradient>.noiseAmount Float default: 0.0 -- animatable, alias: Noise_Amount

When nonzero (ranges from 0 to 1), applies a noise effect. This perturbs the color interpolation parameter using a 3D noise function based on U, V, and Phase.

<Gradient>.noiseType Integer default: 0 -- alias: Noise_Type

Set the type of noise

0- Regular (Generates plain noise. This is the same as Fractal noise with the Levels setting at 1.)

1- Fractal (Generates noise using a fractal algorithm. noiselevels sets the number of iterations for the fractal noise.)

2- Turbulence (Generates fractal noise with an absolute value function applied to it to make fault lines. The noise amount must be greater than 0 to see any effects of turbulence.)

<Gradient>.noiseSize Float default: 1.0 -- animatable, alias: Noise_Size

Scales the noise function. Smaller values give smaller chunks of noise.

<Gradient>.noisePhase Float default: 0.0 -- animatable, alias: Noise_Phase

Controls the speed of the animation of the noise function. A 3D noise function is used for the noise. The first two parameters are U and V and the third is phase.

<Gradient>.noiseLevels Float default: 4.0 -- animatable, alias: Noise_Levels

Sets the number of fractal iterations or turbulence (as a continuous function).

<Gradient>.noiseThresholdLow Float default: 0.0 -- animatable, alias: Low_Threshold

<Gradient>.noiseThresholdHigh Float default: 1.0 -- animatable, alias: High_Threshold

<Gradient>.noiseThresholdSMooth Float default: 0.0 -- animatable, alias: Threshold_Smoothing

When the noise value is above the Low threshold and below the High threshold, the dynamic range is stretched to fill 0-1. This produces a smaller discontinuity at the threshold transition and thus causes less potential aliasing.

noiseThresholdLow: Sets the low threshold.

noiseThresholdHigh: Sets the high threshold.

NoiseThresholdSmooth: Helps make a smoother transition from the threshold value to the noise value. When 0, no smoothing is applied. When it is 1, the maximum amount of smoothing is applied.

<Gradient>.coords StandardUVGen -- alias: coordinates

See UVGenClass for the StandardUVGen properties.

<Gradient>.output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Gradient_Ramp : TextureMap

Constructor

gradient_ramp ...

Properties

<Gradient_Ramp>.Gradient_Type Integer default: 4

The type of gradient:

0- 4 Corner (An asymmetrical linear transition of colors.)

1- Box (A box.)

2- Diagonal (A linear diagonal transition of colors.)

3- Lighting (Based on the light intensity value.)

4- Linear (A smooth, linear transition of colors.)

5- Mapped (Based on the luminance. Remaps the colors of the source map used in the gradient.)

6- Normal (Based on the angle between the vector from the camera to the object and the surface normal vector at the sample point.)

7- Pong (A diagonal sweep that repeats in the middle.)

8- Radial (A radial transition of colors.)

9- Spiral (A smooth, circular transition of colors.)

10- Sweep (A linear sweep transition of colors.)

11- Tartan (A plaid.)

<Gradient_Ramp>.Source_Map_On Integer default: 1

When on, assigns a map to a mapped gradient.

0- Off

1- On

<Gradient_Ramp>.Noise_Type Integer default: 0

Sets the noise type:

0- Regular (Generates plain noise. Basically the same as fractal noise with levels disabled, because Regular is not a fractal function.)

1- Fractal (Generates noise using a fractal algorithm. levels sets the number of iterations for the fractal noise.)

2- Turbulence (Generates fractal noise with an absolute value function applied to it to make fault lines. Note that amount must be greater than 0 to see any effects of turbulence.)

<Gradient_Ramp>.amount Float default: 0.0 -- animatable

When nonzero, a random noise effect is applied to the gradient, based on the interaction of the gradient ramp colors (and maps, if present). The higher this value, the greater the effect.

<Gradient_Ramp>.size Float default: 1.0 -- animatable

Sets the scale of the noise function. Smaller values give smaller chunks of noise.

<Gradient_Ramp>.phase Float default: 0.0 -- animatable

Controls the speed of the animation of the noise function. A 3D noise function is used for the noise; the first two parameters are U and V and the third is phase.

<Gradient_Ramp>.Levels Float default: 4.0 -- animatable

Sets the number of fractal iterations or turbulence (as a continuous function).

<Gradient_Ramp>.Low_Threshold Float default: 0.0 -- animatable

<Gradient_Ramp>.High_Threshold Float default: 1.0 -- animatable

When the noise value is above the Low threshold and below the High threshold, the dynamic range is stretched to fill 0 to 1. This causes a smaller discontinuity at the threshold transition and produces less potential aliasing.

<Gradient_Ramp>.Threshold_Smoothing Float default: 0.0 -- animatable

Helps make a smoother transition from the threshold value to the noise value. When 0, no smoothing is applied. When 1, the maximum amount of smoothing is applied.

<Gradient_Ramp>.coordinates SubAnim

See UVGenClass for the StandardUVGen properties.

<Gradient_Ramp>.output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties.

<Gradient_Ramp>.gradient_ramp SubAnim

<Gradient_Ramp.gradient_ramp>.flag__1 SubAnim

<Gradient_Ramp.gradient_ramp>.flag__2 SubAnim

<Gradient_Ramp.gradient_ramp>.flag__3 SubAnim

<Gradient_Ramp.gradient_ramp.flag__1>.color Point3 default: [255,0,0] -- animatable

<Gradient_Ramp.gradient_ramp.flag__2>.color Point3 default: [0,0,255] -- animatable

<Gradient_Ramp.gradient_ramp.flag__3>.color Point3 default: [0,255,0] -- animatable

<Gradient_Ramp.gradient_ramp.flag__3>.position Float default: [0,255,0] -- animatable

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Marble : TextureMap

Constructor

marble ...

Properties

<Marble>.size Float default: 70.0 -- animatable

Sets the spacing between the veins.

<Marble>.width Float default: 0.025 -- animatable, alias: Vein_width

Sets the width of the veins.

<Marble>.color1 Color default: (color 51 51 25.5) -- animatable, alias: Color_1

The color for the veins.

<Marble>.map1 TextureMap default: undefined -- alias: Map_1

The map used for the veins.

<Marble>.map1Enabled Boolean default: true -- alias: Map_1_Enable

When on, the veins use map1 as their color.

<Marble>.color2 Color default: (color 209.1 209.1 153) -- animatable, alias: Color_2

The color of the background.

<Marble>.map2 TextureMap default: undefined -- alias: Map_2

The map used for the background.

<Marble>.map2Enabled Boolean default: true -- alias: Map_2_Enable

When on, map2 is used for the background.

<Marble>.coords StandardXYZGen -- alias: coordinates

See StandardXYZGen for the StandardXYZGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Mask : TextureMap

Constructor

mask ...

maskTex ...

Properties

<Mask>.map TextureMap default: undefined

The map viewed through the mask.

<Mask>.mapEnabled Boolean default: true -- alias: Map_1_Enable

Enables the map.

<Mask>.mask TextureMap default: undefined

The map to be used as a mask.

<Mask>.maskEnabled Boolean default: true -- alias: Map_2_Enable

Enables the mask map.

<Mask>.maskInverted Boolean default: false -- alias: Invert

When on, inverts the effect of the mask.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Mix : TextureMap

Constructor

mix ...

Properties

<Mix>.color1 Color default: (color 0 0 0) -- animatable, alias: Color_1

The first color to be mixed.

<Mix>.map1 TextureMap default: undefined -- alias: Map_1

Sets a map to be used instead of color1.

<Mix>.map1Enabled Boolean default: true -- alias: Map_1_Enable

When on, map1 is enabled.

<Mix>.color2 Color default: (color 255 255 255) -- animatable, alias: Color_2

The second color to be mixed.

<Mix>.map2 TextureMap default: undefined -- alias: Map_2

Sets a map to be used instead of color2.

<Mix>.map2Enabled Boolean default: true -- alias: Map_2_Enable

When on, map2is enabled.

<Mix>.mixAmount Float default: 0.0 -- animatable, percentage

Determines the proportion of the mix. 0 means only color1 is visible on the surface, 1 means only color2 is visible.

<Mix>.mask TextureMap default: undefined

You can also use a map instead of the mix amount. The two colors will mix in greater or lesser degree according to the intensity of the map.

<Mix>.maskEnabled Boolean default: true -- alias: MaskEnable

When on, mask is used instead of mixAmount.

<Mix>.useCurve Boolean default: false

Determines whether the Mixing Curve effects the mix.

<Mix>.lower Float default: 0.3 -- animatable

<Mix>.upper Float default: 0.7 -- animatable

Adjusts the level of the upper and lower limits. If the two values are the same, the two materials will meet at a definite edge. Wider ranges give more gradual mixing.

<Mix>.output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Noise : TextureMap

Constructor

noise ...

Properties

<Noise>.type Integer default: 0

Sets the type of noise:

0- Regular (Generates plain noise. Basically the same as fractal noise with levels at 1.)

1- Fractal (Generates noise using a fractal algorithm. levels sets the number of iterations for the fractal noise.)

2- Turbulence (Generates fractal noise with an absolute value function applied to it to make fault lines.)

<Noise>.size Float default: 25.0 -- animatable, alias: Noise_Size

Sets the scale of the noise function.

<Noise>.thresholdLow Float default: 0.0 -- animatable, alias: Low_Threshold

<Noise>.thresholdHigh Float default: 1.0 -- animatable, alias: High_Threshold

When the noise value is above the Low threshold and below the High threshold, the dynamic range is stretched to fill 0-1. This creates a smaller discontinuity (technically, 1st order instead of 0 order) at the threshold transition and produces less potential aliasing.

<Noise>.levels Float default: 3.0 -- animatable, alias: Noise_Levels

Determines how much fractal energy is used for the Fractal and Turbulence noise functions. You can set the exact amount of turbulence you want, and also animate the number of fractal levels.

<Noise>.phase Float default: 0.0 -- animatable

Controls the speed of the animation of the noise function. Use this option to animate the noise function.

<Noise>.color1 Color default: (color 0 0 0) -- animatable, alias: Color_1

Sets the first principal noise color.

<Noise>.map1 TextureMap default: undefined -- alias: Map_1

Map used in place of color1.

<Noise>.map1Enabled Boolean default: true -- alias: Map_1_Enable

When on, map1 is enabled.

<Noise>.color2 Color default: (color 255 255 255) -- animatable, alias: Color_2

Sets the second principal noise color.

<Noise>.map2 TextureMap default: undefined -- alias: Map_2

Map used in place of color2.

<Noise>.map2Enabled Boolean default: true -- alias: Map_2_Enable

When on, map2 is enabled.

<Noise>.coords StandardXYZGen -- alias: coordinates

See StandardXYZGen for the StandardXYZGen properties

<Noise>.output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Output : TextureMap

Constructor

output ...

Properties

<output>.map1 TextureMap default: undefined -- alias: Map_1

Map used to apply output settings.

<output>.map1Enabled Boolean default: true -- alias: Map_1_Enable

When on, enables the associated map.

<output>.output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Paint : TextureMap

Note: Paint maps are no longer supported in 3ds max 4.

Constructor

paint ...

Properties

<Paint>.height Integer default: 0 -- animatable

<Paint>.width Integer default: 0 -- animatable

<Paint>.coordinates SubAnim

See UVGenClass for the StandardUVGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Particle_Age : TextureMap

Constructor

particle_age ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Particle_Age>.color1 Color default: (color 0 0 0) -- animatable, alias: Color_1

Sets the color of a particle at its birth.

<Particle_Age>.map1 TextureMap default: undefined -- alias: Map_1

Sets the map used for a particle at its birth.

<Particle_Age>.map1Enabled Boolean default: true -- alias: Map_1_Enable

When on, the associated map is enabled.

<Particle_Age>.age1 Float default: 0.0 -- animatable, alias: Age_1

Sets the age where a particle starts changing from color1 to color2, expressed as a percentage of the particle's entire life.

<Particle_Age>.color2 Color default: (color 127.5 127.5 127.5) -- animatable, alias: Color_2

Sets the color of a particle in mid-life.

<Particle_Age>.map2 TextureMap default: undefined -- alias: Map_2

Sets the map used for a particle in mid-life.

<Particle_Age>.map2Enabled Boolean default: true -- alias: Map_2_Enable

When on, the associated map is enabled.

<Particle_Age>.age2 Float default: 50.0 -- animatable, alias: Age_2

Sets the age where a particle's color equals color2, expressed as a percentage of the particle's entire life.

<Particle_Age>.color3 Color default: (color 255 255 255) -- animatable, alias: Color_3

Sets the color of a particle at its death.

<Particle_Age>.map3 TextureMap default: undefined -- alias: Map_3

Sets the map used for a particle at its death.

<Particle_Age>.map3Enabled Boolean default: true -- alias: Map_3_Enable

When on, the associated map is enabled.

<Particle_Age>.age3 Float default: 100.0 -- animatable, alias: Age_3

Sets the age where a particle changes to color3, expressed as a percentage of the particle's entire life.

<Particle_Age>.output StandardTextureOutput

See TexOutputClass for the StandardTextureOutput properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Particle_MBlur : TextureMap

Constructor

particle_mblur ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Particle_MBlur>.color1 Color default: (color 255 255 255) -- animatable, alias: Color_1

A particle approaches this color as it reaches its slowest speed. By default, this color is white to provide the opaque end of the range for an opacity map.

<Particle_MBlur>.color2 Color default: (color 0 0 0) -- animatable, alias: Color_2

A particle approaches this color as it speeds up. As a default, this color is black to provide transparency in an opacity map.

<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

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Perlin_Marble : TextureMap

Constructor

perlin_marble ...

Properties

<Perlin_Marble>.size Float default: 50.0 -- animatable

Sets the size of the marble pattern. Change this to change the scale of marble, relative to the object's geometry.

<Perlin_Marble>.level Float default: 8.0 -- animatable, alias: Levels

Sets the number of times the turbulence algorithm is applied. Can range from 1.0 to 10.0. The higher the value, the more complicated the marble pattern.

<Perlin_Marble>.color1 Color default: (color 189.975 189.975 160.65) -- animatable, alias: Color_1

The first color used in the marble.

<Perlin_Marble>.saturation1 Float default: 85.0 -- animatable, alias: Color_1_Saturation

Controls the saturation of the color in the map, without altering the color displayed in the color swatch. Lower values darken the color, and higher values lighten it.

<Perlin_Marble>.map1 TextureMap default: undefined

Map used in place of color1.

<Perlin_Marble>.map1Enabled Boolean default: true -- alias: EnableMap1

When on, the associated map is enabled.

<Perlin_Marble>.color2 Color default: (color 59.925 89.25 59.925) -- animatable, alias: Color_2

The second color used in the marble.

<Perlin_Marble>.saturation2 Float default: 70.0 -- animatable, alias: Color_2_Saturation

Controls the saturation of the color in the map, without altering the color displayed in the color swatch. Lower values darken the color, and higher values lighten it.

<Perlin_Marble>.map2 TextureMap default: undefined

Map used in place of color2.

<Perlin_Marble>.map2Enabled Boolean default: true -- alias: EnableMap2

When on, the associated map is enabled.

<Perlin_Marble>.coords StandardXYZGen -- alias: Coordinates

See StandardXYZGen for the StandardXYZGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Planet : TextureMap

Constructor

planet ...

Properties

<Planet>.color1 Color default: (color 10.2 20.4 79.05) -- animatable, alias: Color_1

The color at the center of the water mass.

<Planet>.color2 Color default: (color 10.2 30.6 79.05) -- animatable, alias: Color_2

The color surrounding the center of the water mass.

<Planet>.color3 Color default: (color 10.2 40.8 79.05) -- animatable, alias: Color_3

The color surrounding color2, meeting the land.

<Planet>.color4 Color default: (color 10.2 99.45 12.75) -- animatable, alias: Color_4

<Planet>.color5 Color default: (color 99.45 79.05 12.75) -- animatable, alias: Color_5

<Planet>.color6 Color default: (color 79.05 20.4 7.65) -- animatable, alias: Color_6

<Planet>.color7 Color default: (color 99.45 79.05 51) -- animatable, alias: Color_7

<Planet>.color8 Color default: (color 99.45 99.45 99.45) -- animatable, alias: Color_8

The colors in these five swatches are applied to the land areas of the planet surface. Their arrangement continues that of the water colors. color4 is the shoreline of the land, meeting the water; color5 comes next, working toward the center of the land mass. color8 is at the center of the land mass.

<Planet>.continentSize Float default: 40.0 -- animatable, alias: Continent_Size

Sets the size of the fractal noise pattern used to generate the continents. Can range from 0 to 100. The higher the value, the larger the continents.

<Planet>.islandFactor Float default: 0.5 -- animatable, alias: Island_Factor

Sets the size of the fractal noise pattern used to generate islands and mountains. Can range from 0 to 100. At 0, the geography is very low. Higher settings create a more rugged landscape.

<Planet>.oceanPercent Float default: 60.0 -- animatable, alias: Ocean_Percent

Sets the percentage of the planet's surface that is covered by water.

<Planet>.randomSeed Integer default: 12345

Sets the seed for pseudo-random generation of the pattern. Changing this number can completely change the pattern, even if other settings remain the same. On the other hand, a different Planet map with the same settings including the same Random Seed will appear the same.

<Planet>.blendWaterLand Boolean default: true

When on, the boundary between water and land is blended, giving a hazy appearance. When off, the boundary between water and land is sharp.

<Planet>.coords StandardXYZGen -- alias: Coordinates

See StandardXYZGen for the StandardXYZGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Raytrace : TextureMap

Constructor

raytrace ...

Properties

<Raytrace.parameters>.Trace_Mode Integer default: 0

Sets whether to cast reflected or refracted rays:

0- 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.)

1- Reflection (Casts reflected rays off the object's surface.)

2- Refraction (Casts refracted rays into or through the object's surface.)

<Raytrace.parameters>.Options__Raytracer_Enable Boolean default: true -- animatable

Turns the raytracer on or off. Even with raytracing off, Raytrace material and Raytrace map still reflect and refract the environment, including both the environment map for the 3ds max scene, and the environment map assigned to the Raytrace material.

<Raytrace.parameters>.Options__Antialiasing_Enable Boolean default: true -- animatable

Turns antialiasing on or off. Antialiasing is possibly the slowest portion of raytrace rendering.

<Raytrace.parameters>.Options__Self_Reflect_Refract Boolean default: true -- animatable

Turns self reflection/refraction on or off.

<Raytrace.parameters>.Options__Raytrace_Atmospherics Boolean default: true -- animatable

Turns the raytracing of atmospheric effects on or off. Atmospheric effects include fire, fog, volume light, and so on.

<Raytrace.parameters>.Options__Reflect_Refract_Material_ID_s Boolean default: true -- animatable

When on, the material reflects effects assigned to material IDs in the renderer's G-buffer on or off.

<Raytrace.parameters>.Options__Raytrace_Objects_in_Glass Boolean default: true -- animatable

Turns the raytracing of objects inside raytraced objects on or off.

<Raytrace.parameters>.Options__Raytrace_Atmospherics_in_Glass Boolean default: true -- animatable

Same as the previous control, but for atmospheric effects instead of objects.

<Raytrace.parameters>.Options__Color_Density___Fog_Enable Boolean default: true -- animatable

Turns the color density and fog features on or off.

<Raytrace.parameters>.Background_Mode Integer default: 0

Sets Background Mode:

0- Use Environment Settings (Respects the environment settings of the current scene.)

1- Use Background_Color (Overrides environment settings)

2- Use background map (Overrides the environment settings with the specified map.)

<Raytrace.parameters>.Background_Color Color default: (color 0 0 0) -- animatable

Color used as background.

<Raytrace.parameters>.Local_Antialias_Override Boolean default: false

When on, allows you to modify local anitialiasing settings.

<Raytrace.parameters>.Adaptive_Antialiasing Boolean default: false

When on, enables the adaptive antialiaser for this Raytrace map.

<Raytrace.parameters>.Local_Threshold Float default: 0.1 -- animatable

Determines the sensitivity of the adaption algorithm. This value can range from 0 to 1, where 0 always casts the maximum number of rays and 1 always casts only the minimum number of rays.

<Raytrace.parameters>.Local_Min__Rays Integer default: 4 -- animatable

Sets the initial number of rays cast per pixel.

<Raytrace.parameters>.Local_Max_Rays Integer default: 32 -- animatable

Sets the maximum number of rays the algorithm casts.

<Raytrace.parameters>.Local_Blur_Offset Float default: 0.0 -- animatable

Affects the sharpness or blurriness of reflections or refractions without regard to distance. You can use this to soften the details of a reflection or refraction. This value is specified in pixels.

<Raytrace.parameters>.Local_Blur_Aspect Float default: 1.0 -- animatable

Changes the shape of the blur by changing the aspect ratio. Usually you will not need to change this setting.

<Raytrace.parameters>.Local_Defocus_Amount Float default: 0.0 -- animatable

Blurs based on distance. Objects near the surface are not blurred, but objects farther away are blurred. The rays cast are spread as they leave the surface of the Raytrace map object.

<Raytrace.parameters>.Local_Defocus_Aspect Float default: 1.0 -- animatable

Changes the shape of the defocusing by changing the aspect ratio. Usually you will not need to change this setting.

<Raytrace.parameters>.Use_Blur_Map Boolean default: false

When on, uses a map to apply the Blur Offset value. That is, where the map is white, blur offset is fully applied, and where it is black, it is ignored. For example, if the map is a Checker map, blur offset is applied only in every other square. Values between black and white cause less blur.

<Raytrace.parameters>.Use_Defocus_Map Boolean default: false

When on, uses a map to apply the Defocus value. That is, where the map is white, Defocus is fully applied, and where it is black, it is ignored. For example, if the map is a Checker map, Defocus is applied only in every other square. Values between black and white cause less defocusing.

<Raytrace.parameters>.Attenuation_Mode Integer default: 0

Sets Attenuation Mode:

0- Off

1- Linear (Linear attenuation is calculated between the attenuation_start and attenuation_end values.)

2- 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.)

3- Exponential (Sets exponential attenuation. Exponential attenuation is calculated between the attenuation_start and attenuation_end values. You also specify the exponent to use.)

4- Custom Falloff (Specifies a custom curve to use for attenuation.)

<Raytrace.parameters>.Attenuation_Start Float default: 0.0 -- animatable

The distance in world units where attenuation begins.

<Raytrace.parameters>.Attenuation_End Float default: 100.0 -- animatable

<Raytrace.parameters>.Attenuation_Exponent Float default: 2.0 -- animatable

<Raytrace.parameters>.Attenuation_Color_Mode Integer default: 0

Attenuation_Color_Mode = 0 - Background; 1 - use Attenuation_Color

<Raytrace.parameters>.Attenuation_Color Color default: (color 0 0 0) -- animatable

Sets the distance in world units where the ray is fully attenuated.

<Raytrace.parameters>.Attenuation_Near Float default: 1.0 -- animatable

Sets the strength of the reflected/refracted ray at the start range distance. This is a normalized percentage that can range from 0.0 to 1.0.

<Raytrace.parameters>.Attenuation_Control_1 Float default: 0.6666 -- animatable

Controls the shape of the curve near the curve start.

<Raytrace.parameters>.Attenuation_Control_2 Float default: 0.3333 -- animatable

Controls the shape of the curve near the curve end.

<Raytrace.parameters>.Attenuation_Far Float default: 0.0 -- animatable

Sets the strength of the reflected/refracted ray at the end range distance. This is a normalized percentage that can range from 0.0 to 1.0.

<Raytrace.parameters>.Use_Reflectivity_Map Boolean default: false -- animatable

Enables a reflectivity map.

<Raytrace.parameters>.Reflectivity_Map_Amount Float default: 1.0 -- animatable

Controls the amount of raytracing used by the material it is assigned to.

<Raytrace.parameters>.Basic_Tint_Enable Boolean default: false

Turns basic tinting on or off.

<Raytrace.parameters>.Tint_Amount Float default: 1.0 -- animatable

Sets the amount of tinting used.

<Raytrace.parameters>.Tint_Color Color default: (color 255 255 255) -- animatable

Assigns a tint color for reflections.

<Raytrace.parameters>.Use_Tint_Map Boolean default: false

Enables the use of a map for tinting.

<Raytrace.parameters>.Color_Density_Enable Boolean default: false

Turns color density on or off.

<Raytrace.parameters>.Color_Density_Color Color default: (color 255 255 255) -- animatable

Sets the transmission color.

<Raytrace.parameters>.Color_Density_Amount Float default: 1.0 -- animatable

Controls the amount of density color. It can range from 0 to 1.0. Reducing this value reduces the density color effect.

<Raytrace.parameters>.Color_Density_Start Float default: 0.0 -- animatable

<Raytrace.parameters>.Color_Density_End Float default: 25.0 -- animatable

A thin piece of tinted glass is mainly clear, while a thick piece of the same glass has more color. Start and End Distance, expressed in world units, controls help you simulate this effect. Start is the position in the object where the density color begins to appear. End is the position in the object where the density color reaches its full Amount value. To have a lighter effect, increase the End value. To have a heavier effect, reduce the End value.

<Raytrace.parameters>.Use_Color_Density_Map Boolean default: false

Enables the use of a map for the color density filter.

<Raytrace.parameters>.Fog_Enable Boolean default: false

Turns fog on or off.

<Raytrace.parameters>.Fog_Color Color default: (color 255 255 255) -- animatable

Sets the fog color.

<Raytrace.parameters>.Fog_Amount Float default: 1.0 -- animatable

Controls the amount of density fog. It can range from 0 to 1.0. Reducing this value reduces the density fog effect and makes the fog translucent.

<Raytrace.parameters>.Fog_Start Float default: 0.0 -- animatable

<Raytrace.parameters>.Fog_End Float default: 25.0 -- animatable

Start and End Distance controls, expressed in world units, adjust the fog effect based on the object's dimensions. Start is the position in the object where the density fog begins to appear. End is the position in the object where the density fog reaches its full Amount value. To have a lighter effect, increase the End value. To have a heavier effect, reduce the End value.

<Raytrace.parameters>.Use_Fog_Map Boolean default: false

Enables a map for the fog color.

The following properties do not correspond to any user-interface items, and may or may not be used by the raytracer.

<Raytrace.parameters>.Interobject_Interphase_Fusing Boolean default: false

<Raytrace.parameters>.IIF_Tolerance Float default: 1.0

Notes

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

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Reflect_Refract : TextureMap

Constructor

reflect_refract ...

Properties

<Reflect_Refract>.source Integer default: 0

Chooses the source of the six cubic maps:

0- 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.)

1- From File (When on, you can specify the bitmaps to use.)

<Reflect_Refract>.size Integer default: 100 -- animatable

Sets the size of the Reflect/Refract maps. The default value of 100 produces distinct images. Lower values lose progressively more detail.

<Reflect_Refract>.useAtmosphericMap Boolean default: true -- alias: Use_Atmospheric

When off, environment maps are ignored by Reflect/Refract map during rendering. It's useful to turn this off when you have mirrors in the scene and you're rotoscoping against a flat screen environment map. A screen environment map does not exist in 3D space the way the other environment-map types do, and will not render properly.

<Reflect_Refract>.apply Boolean default: true

Turns on filtering to blur the maps.

<Reflect_Refract>.blurOffset Float default: 0.0 -- animatable, alias: Blur_Offset

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

<Reflect_Refract>.blur Float default: 1.0 -- animatable

Affects the sharpness or blurriness of the generated map based on its distance from the object. The farther away the map is, the greater the blurring. Blur is primarily used to avoid aliasing. It's a good idea to use a small amount of blurring for all maps in order to avoid the scintillation or aliasing that can occur when pixel details are reduced off in the distance.

<Reflect_Refract>.near Float default: 0.0 -- animatable, alias: Near_Value

Sets the near range for fog.

<Reflect_Refract>.far Float default: 500.0 -- animatable, alias: Far_Value

Sets the far range for fog.

<Reflect_Refract>.frametype Integer default: 0

Sets the frame type:

0- First Frame Only (Tells the renderer to create automatic maps only on the first frame.)

1- Every Nth Frame (Tells the renderer to create animated auto maps based on nthframe.)

<Reflect_Refract>.nthframe Integer default: 1

Sets the frame rate for automatic maps.

<Reflect_Refract>.bitmapName ArrayParameter default: #(undefined, ... , undefined)

Array with 6 elements. Each element stores a string reflecting the name of a source bitmap file.

<Reflect_Refract>.outputname String default: undefined—alias: Output_Name

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


RGB_Multiply : TextureMap

Constructor

rgb_multiply ...

Properties

<RGB_Multiply>.color1 Color default: (color 255 255 255) -- animatable, alias: Color_1

<RGB_Multiply>.map1 TextureMap default: undefined -- alias: Map_1

<RGB_Multiply>.map1Enabled Boolean default: true -- alias: Map_1_Enable

Enables associated map.

<RGB_Multiply>.color2 Color default: (color 255 255 255) -- animatable, alias: Color_2

<RGB_Multiply>.map2 TextureMap default: undefined -- alias: Map_2

<RGB_Multiply>.map2Enabled Boolean default: true -- alias: Map_2_Enable

Enables associated map.

<RGB_Multiply>.alphaFrom Integer default: 2

Determines how to generate alpha for the map:

0- Map #1 (Uses the first map's alpha channel.)

1- Map #2 (Uses the second map's alpha channel.)

2- Multiply Alphas (Generates a new alpha channel by multiplying the alpha channels of the two maps.)

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


RGB_Tint : TextureMap

Constructor

rgb_tint ...

Properties

<RGB_Tint>.red Color default: (color 255 0 0) -- animatable

The tint of the red color channel.

<RGB_Tint>.green Color default: (color 0 255 0) -- animatable

The tint of the green color channel.

<RGB_Tint>.blue Color default: (color 0 0 255) -- animatable

The tint of the blue color channel.

<RGB_Tint>.map1 TextureMap default: undefined -- alias: Map_1

Sets the map to be tinted.

<RGB_Tint>.map1Enabled Boolean default: true -- alias: Map_1_Enable

Enable the effect of map1.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Smoke : TextureMap

Constructor

smoke ...

Properties

<Smoke>.size Float default: 40.0 -- animatable

Changes the scale of the smoke "clumps."

<Smoke>.iterations Integer default: 5 -- animatable

Sets the number of times the fractal function is applied. The higher the value, the more detail within the smoke, but the longer the calculation time.

<Smoke>.phase Float default: 0.0 -- animatable

Shifts the turbulence within the smoke pattern. Animate this parameter to animate the movement of the smoke.

<Smoke>.exponent Float default: 1.5 -- animatable

Makes color2, representing the smoke, sharper and more wispy. As this value increases, the smoke "tendrils" become smaller within the pattern.

<Smoke>.color1 Color default: (color 0 0 0) -- animatable, alias: Color_1

The smokeless portion of the effect.

<Smoke>.map1 TextureMap default: undefined

The map used for the smokeless portion of the effect.

<Smoke>.map1On Boolean default: true -- alias: Map1_On

Enables the associated map.

<Smoke>.color2 Color default: (color 229.5 229.5 229.5) -- animatable, alias: Color_2

The color of the smoke.

<Smoke>.map2 TextureMap default: undefined

The map used for the smoke.

<Smoke>.map2On Boolean default: true -- alias: Map2_On

Enables the associated map.

<Smoke>.coords StandardXYZGen -- alias: Coordinates

See StandardXYZGen for the StandardXYZGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Speckle : TextureMap

Constructor

speckle ...

Properties

<Speckle>.size Float default: 60.0 -- animatable

Adjusts the size of the speckles. Use this to make the speckles match your geometry.

<Speckle>.color1 Color default: (color 51 127.5 255) -- animatable, alias: Color_1

The color of the speckles.

<Speckle>.map1 TextureMap default: undefined

The map used as the color of the speckles.

<Speckle>.map1On Boolean default: true -- alias: Map1_On

Enables associated map.

<Speckle>.color2 Color default: (color 178.5 204 204) -- animatable, alias: Color_2

The color of the background.

<Speckle>.map2 TextureMap default: undefined

The map used as the color of the background.

<Speckle>.map2On Boolean default: true -- alias: Map2_On

Enables associated map.

<Speckle>.coords StandardXYZGen -- alias: Coordinates

See StandardXYZGen for the StandardXYZGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Splat : TextureMap

Constructor

splat ...

Properties

<Splat>.size Float default: 40.0 -- animatable

Adjusts the size of the splats. Use this to make the splats match your geometry.

<Splat>.iterations Integer default: 4 -- animatable

Sets the number of times the fractal function is evaluated. The higher the number, the more detailed the splats, but the longer the calculation time.

<Splat>.threshold Float default: 0.2 -- animatable

Determines how much of color1 is mixed with color2. At 0, only color1 is displayed; at 1, only color2 is displayed.

<Splat>.color1 Color default: (color 178.5 204 204) -- animatable, Color_1

The color of the background.

<Splat>.map1 TextureMap default: undefined

The map used as the color of the background.

<Splat>.map1On Boolean default: true -- alias: Map1_On

Enables associated map.

<Splat>.color2 Color default: (color 51 127.5 255) -- animatable, Color_2

The color of the splats.

<Splat>.map2 TextureMap default: undefined

The map used as the color of the splats.

<Splat>.map2On Boolean default: true -- alias: Map2_On

Enables associated map.

<Splat>.coords StandardXYZGen -- alias: Coordinates

See StandardXYZGen for the StandardXYZGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Stucco : TextureMap

Constructor

stucco ...

Properties

<Stucco>.size Float default: 20.0 -- animatable

Adjusts the size of the indentations. Use this to make the scale of the stucco match your geometry.

<Stucco>.thickness Float default: 0.15 -- animatable

Blurs the border between the two colors. At 0, the borders are sharp. The higher the Thickness, the more the borders are blurred and the less distinct the indentations are. When you use Stucco as a bump map, the indentations are very faint at 0.5 and disappear at values not much greater.

<Stucco>.threshold Float default: 0.57 -- animatable

Determines how much of color1 is mixed with color2. At 0, only color1 is displayed; at 1, only color2 is displayed.

<Stucco>.color1 Color default: (color 0 0 0) -- animatable, alias: Color_1

The color of the indentations.

<Stucco>.map1 TextureMap default: undefined

The map used as the color of the indentations.

<Stucco>.map1On Boolean default: true -- alias: Map1_On

Enables associated map.

<Stucco>.color2 Color default: (color 229.5 229.5 229.5) -- animatable, alias: Color_2

The background stucco color.

<Stucco>.map2 TextureMap default: undefined

The map used as the background stucco color.

<Stucco>.map2On Boolean default: true -- alias: Map2_On

Enables associated map.

<Stucco>.coords StandardXYZGen -- alias: Coordinates

See StandardXYZGen for the StandardXYZGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Swirl : TextureMap

Constructor

swirl ...

Properties

<Swirl>.Base Color default: (color 229.5 147.9 76.5) -- animatable

The underlying layer for the swirl effect.

<Swirl>.Swirl Color default: (color 0 25.5 51) -- animatable

Mixed with the Base color or map, produces the swirl effect.

<Swirl>.Color_Contrast Float default: 0.4 -- animatable

Controls the contrast between Base and Swirl. At 0, the swirl is blurred. Higher values increase the contrast until all colors become black and white, even if Swirl Intensity and Swirl Amount are very high.

<Swirl>.Swirl_Intensity Float default: 2.0 -- animatable

Controls the intensity of the swirl color. Higher values create a more vibrant mix of colors. At 0, the swirl effect disappears.

<Swirl>.Swirl_Amount Float default: 1.0 -- animatable

Controls the quantity of the swirl color that gets mixed into the base color. If set to 0, only the base color is used.

<Swirl>.Twist Float default: 1.0 -- animatable

Changes the number of spirals in the swirl effect. Higher values increase the number of spirals. Negative values change the direction of the twist. At 0, the colors are randomly distributed, not swirled.

<Swirl>.Constant_Detail Integer default: 4 -- animatable

Changes the level of detail within a swirl. Lower values minimize the level of detail within the swirl. At 0, all detail is lost. Higher values increase detail until the swirl effect disappears.

<Swirl>.Center_Position_Y Float default: -0.5 -- animatable

<Swirl>.Center_Position_X Float default: -0.5 -- animatable

Adjusts the location of the swirl's center on the object.

<Swirl>.Lock_Background Integer default: 1

X and Y values remain identical as you adjust them. By turning off Lock and adjusting either the X or Y position, you can "slide" the swirl effect across the object.

0- Off

1- 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 UVGenClass for the StandardUVGen properties.

Notes

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

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Thin_Wall_Refraction : TextureMap

Constructor

thin_wall_refraction ...

Properties

<Thin_Wall_Refraction>.applyBlur Boolean default: true

Turns on filtering to blur the maps.

<Thin_Wall_Refraction>.blur Float default: 1.0 -- animatable

Affects the sharpness or blurriness of the generated map based on its distance from the object. The farther away the map is, the greater the blurring. Blur is primarily used to avoid aliasing. It's a good idea to use a small amount of blurring for all maps in order to avoid the scintillation or aliasing that can occur when pixel details are reduced off in the distance.

<Thin_Wall_Refraction>.frame Integer default: 0

Affects how the refraction should behave in animations:

0- First Frame Only (Tells the renderer to create the refracted image only on the first frame.)

1- Every Nth Frame (Tells the renderer to regenerate the refracted image based on nthframe.)

<Thin_Wall_Refraction>.nthFrame Integer default: 1

Sets the regeneration rate in animations.

<Thin_Wall_Refraction>.useEnviroment Boolean default: true

When off, environment maps are ignored by the refraction during rendering. It's useful to turn it this off when you have refractions in the scene and you're rotoscoping against a flat screen environment map. A screen environment map does not exist in 3D space the way the other environment map types do, and will not render properly.

<Thin_Wall_Refraction>.thicknessOffset Float default: 0.5 -- animatable, alias: Thickness_Offset

Affects the size of the refractive offset, or jog effect. At 0, there's no offset, and the object can appear invisible in the rendered scene. At 10.0, the offset is at its greatest.

<Thin_Wall_Refraction>.bumpMapEffect Float default: 1.0 -- animatable, alias: Bump_Map_Effect

Affects the magnitude of refraction due to the presence of a bump map. This parameter multiplies the current bump map Amount in the parent material. Reduce this value to reduce the effect of the secondary refraction; increase this value to increase the effect. If there is no bump map assigned, this value has no effect.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Vertex_Color : TextureMap

Constructor

vertex_color ...

Properties

There are no additional properties for vertex_color.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Water : TextureMap

Constructor

water ...

Properties

<Water>.numWaveSets Integer default: 10 -- animatable, alias: Num_Wave_Sets

Specifies how many wave sets are used in the pattern. Wave sets are groups of radially symmetrical waves that originate from randomly computed points along the surface of an imaginary sphere inside the object (a circle, in the case of 2D wave distribution). For calm water, set this to a low number. Use a high number for choppy water.

<Water>.waveRadius Float default: 800.0 -- animatable, alias: Wave_Radius

Specifies the radius, in 3ds max units, of the imaginary sphere (3D distribution) or circle (2D distribution) whose surface is the origin of each wave set. A large radius produces large circular wave patterns, while a small radius produces dense, smaller waves.

<Water>.waveLenMax Float default: 50.0 -- animatable

<Water>.waveLenMin Float default: 5.0 -- animatable

Define the interval used to randomly chose each wave center. If these two values are close together, the water appears more regular. If they're farther apart, the water is less regular.

<Water>.amplitude Float default: 1.0 -- animatable

Adjusts the strength and the depth of the waves by increasing the contrast between the two colors.

<Water>.phase Float default: 0.0 -- animatable

Shifts the wave pattern. Animate this parameter to animate the motion of the pattern.

<Water>.distribution Integer default: 0

3D distributes the wave centers on the surface of an imaginary sphere, affecting all sides of a 3D object. 2D distributes the wave in circles centered on the XY plane, which is more appropriate for flat water surfaces such as oceans and lakes.

0- 3D

1- 2D

<Water>.randomSeed Integer default: 30159

Provides a seed number to generate the water pattern. The pattern changes with each seed, but all other settings are maintained.

<Water>.color1 Color default: (color 198.9 198.9 239.7) -- animatable, alias: Color_1

Sets the wave trough color.

<Water>.map1 TextureMap default: undefined

Sets a map as the wave trough color.

<Water>.map1On Boolean default: true -- alias: Map1_On

Enables associated map.

<Water>.color2 Color default: (color 25.5 25.5 198.9) -- animatable, alias: Color_2

The color of wave peaks.

<Water>.map2 TextureMap default: undefined

Sets a map as the color of wave peaks.

<Water>.map2On Boolean default: true -- alias: Map2_On

Enables associated map.

<Water>.coords StandardXYZGen -- alias: Coordinates

See StandardXYZGen for the StandardXYZGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Wood : TextureMap

Constructor

wood ...

Properties

<Wood>.thickness Float default: 7.0 -- animatable, alias: Grain_Thickness

Sets the relative thickness of the color bands that make up the grain.

<Wood>.radialNoise Float default: 1.0 -- animatable, alias: Radial_Noise

Sets the relative randomness of the pattern on a plane perpendicular to the grain, the circular ring structure.

<Wood>.axialNoise Float default: 1.0 -- animatable, alias: Axial_Noise

Sets the relative randomness of the pattern on a plane parallel with the grain, along the length of the grain.

<Wood>.color1 Color default: (color 201.45 175.95 68.85) -- animatable, alias: Color_1

<Wood>.map1 TextureMap default: undefined

<Wood>.map1Enabled Boolean default: true -- alias: MapOn1

Enables associated map.

<Wood>.color2 Color default: (color 130.05 81.6 12.75) -- animatable, alias: Color_2

<Wood>.map2 TextureMap default: undefined

<Wood>.map2Enabled Boolean default: true -- alias: MapOn2

Enables associated map.

<Wood>.coords StandardXYZGen -- alias: Coordinates

See StandardXYZGen for the StandardXYZGen properties.

See also

TextureMap Common Properties, Operators, and Methods

Material Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

Time and Key Functions on Object Hierarchies

Controllers - Superclass Level

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.


Controller Common Properties, Operators, and Methods

Properties

All controllers have the following properties:

<controller>.keys MAXKeyArray—read-only, the controller's key array

<controller>.value varies -- get or set the current controller value

The keys and value properties give you access to the value and keys in a free-standing controller, which is useful when working with the global tracks controllers that are accessible in MAXScript. Those controllers that are not keyframeable return an empty KeyArray for their keys property.

The value property is sensitive to the current time and animate contexts, so you can use it to evaluate a controller at various times or to plant keyframes in those controllers that support keys.

You can only assign a value to a controller's value property if the controller is a key-based controller. The only exception to this is that you can assign a Matrix3 value to a PRS controller's value property. MAXScript will automatically set the individual position, rotation, and scale values to the values represented in the Matrix3 value.

If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available:

<controller>.Ease_Curve Float -- the controller's ease curve value

If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available:

<controller>.Multiplier_Curve Float -- the controller's multiplier curve value

See Ease and Multiplier Curve Functions for methods and notes related to ease and multiplier curves.

Example

globaltracks.float.mycontroller.value

globaltracks.float.mycontroller.keys[2]

Associated Properties

All animatable properties in 3ds max objects let you reference several controller-related sub-properties. These are:

<property>.controller -- the property's controller

<property>.track -- a synonym for .controller

<property>.isAnimated -- a boolean indicating whether the property is animated

<property>.keys -- read-only, gets the property's controller's key array

The track property is a simple synonym for controller. If an animatable property does not yet have a controller assigned, the isAnimated property returns false and the controller, track, and keys properties return undefined.

Example:

$foo.pos.controller

bend_mod1.angle.isAnimated

$bar.taper.gizmo.scale.keys[2]

You create controllers as you do other 3ds max objects by calling the class as a function:

c = bezier_position()

and assign them to animatable properties by assigning to the controller property in those animatables.

Example:

$foo.pos.controller = c

$baz.bend.gizmo.rotation.controller = tcb_rotation()

$box01.length = linear_float()

Methods

getPointControllers {<editable_mesh_node> | <editable_spline_node>}

Returns an array of controllers assigned to the vertices in the mesh or spline. If no controller has been assigned to a vertex, the array element value will be undefined. For editable splines, each knot consists of 3 vertices: the in vector, the knot, and the out vector. The array of controllers returned is a "snapshot" of the current controllers. If controllers are assigned or changed for a vertex, this change is not reflected in the array. If a vertex is added/deleted, the array is not resized to reflect the change in number of vertices.

getPointController <editable_mesh_node> <vertex_index_integer>

Returns the controller currently assigned to the vertex, undefined if no controller assigned.

getPointController <editable_spline_node> <spline_index_integer> <vertex_index_integer>

Returns the controller for specified vertex in the specified spline, undefined if no controller assigned. Each spline knot consists of 3 vertices: the in vector, the knot, and the out vector.

Notes

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.

Script:

a=bezier_float()

addnewkey a 0

addnewkey a 10

a.keys[1].value=10

a.keys[2].value=100

b=box()

b.height

b.height.controller=a

b.height

at time 10 b.height

Output:

Controller:Bezier_Float -- result line 1

#Bezier Float key(1 @ 0f) -- result line 2

#Bezier Float key(2 @ 10f) -- result line 3

10 -- result line 4, key value at time 0

100 -- result line 5, key value at time 10

$Box:Box01 @ [0.0,0.0,0.0] -- result line 6

25.0 -- result line 7, default property value

Controller:Bezier_Float -- result line 8

25.0 -- result line 9, key value changed from 10 to 25 (delta= +15)

115.0 -- result line 10, key value changed by delta = +15

A somewhat strange situation can arise when a single controller is assigned to multiple object properties. The value actually stored in a controller may not necessarily be the same value seen in Track View or in the command panels, nor the same value returned by accessing the property value in MAXScript. Part of a MAXWrapper property definition is scaling value that is applied when reading or setting the true value stored in a controller. For example, the slice_to and slice_from properties associated with many of the geometry primitives is displayed in degrees. The actual value stored in the controller associated with these properties are in radians. This scaling factor is an internal property of the MAXWrapper property, and not an internal property of the controller. Both 3ds max and MAXScript automatically apply the specified scaling factor when accessing properties, so this scaling is normally invisible to the user. If the same controller is assigned to two properties which have different scaling factors, the question arises as to which scaling factor to apply to the output of the controller. If you are accessing the controller's value through a MAXWrapper property, the scaling factor associated with that property is applied to the controller's value. MAXScript also internally stores the last scaling factor applied to the controller's value. If you are directly accessing the value property of the controller, or the value property of a key in the controller, the stored scaling factor is used. This can result in a controller's value property returning different values at different times in a script, based on how the controller was last accessed. Because of this, it is highly recommended that you do not instance a controller onto multiple MAXWrapper properties which have different scaling factors. The scaling factor, if any, is listed for each MAXWrapper property in the documentation of the MAXWrapper classes.

Methods

displayControlDialog <controller> <string>

Displays the modal controller dialog, if any. The string will be in the dialog title bar. If the controller is a keyframe controller, the key info dialog will be displayed for the selected keys. If no keys are selected, no dialog will be displayed.

Controllers that can be keyframed support several time and key-related functions, as described in the following topics:

Controller Time Functions

Controller Key Functions

Controller Out-Of-Range Functions

Controller Ease and Multiplier Curve Functions

Controller Key Reducer

See also

Key Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Controller Time Functions

supportsTimeOperations <ctrl>

returns true or false depending on whether the controller supports the following time operations

deleteTime <controller> <interval> [ #incLeft ] [ #incRight ] [ #noSlide ]

Deletes an interval of time from the controller, removing all the keys with that interval and, by default, sliding the keys to the right of the interval to the left by the width of the interval. The optional symbolic arguments choose one of several options:

#incLeft: includes any key exactly at the start time of the interval

#incRight: includes any key exactly at the end time of the interval

#noSlide: doesn't slide the later keys to fill in the gap removed- this effectively just deletes any keys in the interval.

The <interval> argument can be specified as an Interval value or as two numbers or time values defining the start and end times. Number values are taken as frame numbers.

reverseTime <controller> <interval> [ #incLeft ] [ #incRight ]

Reverses time in the given interval, essentially swapping keys around so that their time placements are reversed within the interval. The notes on inclusion and interval arguments from deleteTime() apply.

scaleTime <controller> <interval> <float_scale>

Scales the times of the keys within the given interval. Again, the <interval> argument can be specified as an Interval value or as two numbers or time values defining the start and end times. Number values are taken as frame counts.

insertTime <controller> <at_time> <amount_time>

Inserts a block of time at the specified time, effectively moving all later keys out in time by the amount inserted. The times can be numbers or Time values. Numbers are taken as frame counts.

getTimeRange <controller> [ #selOnly ] [ #allKeys ] [ #children ]

Returns a time Interval value specifying the range of time covered by keys in the controller. The optional symbolic arguments specify options:

#selOnly: return the time range covered by the currently selected keys (in the track view)

#allKeys (default): the time range for all keys in the controller

#children: descends into sub-controllers and returns the total time interval covering all keys in all sub-controllers

setTimeRange <controller> [ <interval> ] [ #linkToKeys ]

Sets the time range to be an interval other than that covered by existing keys, typically to influence when the out-of-range methods take over. If the optional #linkToKeys argument is given any keys exactly at the start or end of the given interval become anchors for the time range and moving them move the time range for the controller.

If you call setTimeRange() with just the single argument, #linkToKeys, it will set the time range to the current start and end keys in all the controllers affected:

setTimeRange $box* #linkToKeys

This is equivalent to the Recouple Ranges function in the Position Ranges mode in Track View.

The following script shows example usages of some of the above methods.

Example:

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

bhk

at time 10 animate on b.height=150

for k in bhk do format "%:%\n" k.time k.value

reversetime bhc 5 15 #incLeft #incRight

for k in bhk do format "%:%\n" k.time k.value

insertTime bhc 12 5

bhk

getTimeRange bhc


Controller Key Functions

addNewKey <controller> <time> [ #select ]

Adds a new key to the controller track at the time specified. The value for the new key is the interpolated controller value at the specified time. The new key is also selected if the #select optional argument is specified. The value for the new key is the interpolated controller value at that time. addNewKey() will not add a key if a key already exists at the specified time. The return value in this case is the key located at the specified time.

This function returns a MAXKey value representing the key so you can set its various properties. See Controller Key Functions for details.

deleteKeys <controller> [ #allKeys ] [ #selection ]

Deletes keys from the controller according to the optional symbolic argument supplied.

#allKeys (default): deletes all keys in the controller.

#selection: deletes the currently selected keys

deleteKey <controller> <index>

Deletes the indexed key. Key indexes are 1-based.

selectKeys <controller> [ <interval> | <time> ]

Selects the specified keys in the track view. If an interval is given, all the keys within the interval are selected. If a single time is given, the key at that time is selected. If no time or interval is given, select all keys.

deselectKeys <controller> [ <interval> | <time> ]

Deselects specified keys. Arguments are as described in selectKeys().

selectKey <controller> <index_integer>

Selects the indexed key. Key indexes are 1-based.

isKeySelected <controller> <index_integer>

Returns true if indexed key is selected, false otherwise. Key indexes are 1-based.

deselectKey <controller> <index_integer>

Deselects the indexed key. Key indexes are 1-based.

moveKeys <controller> <time> [ #selection ]

Moves the specified keys by the time given. If #selection is specified, move the current selection otherwise move all keys.

moveKey <controller> <index_integer> <time>

Move the indexed key by the specified time.

numKeys <controller>

Returns the number of keys in the controller. Returns -1 if you call it on a controller that does not support keyframing.

getKey <controller> <index_integer>

Returns the indexed key as a MAXKey instance. See Controller Key Functions for MAXKey class information.

getKeyTime <controller> <index_integer>

Returns the time of indexed key.

getKeyIndex <controller> <time>

Returns the index of the key at the specified time.

numSelKeys <controller>

Returns the number of keys currently selected in the track view.

sortKeys <controller>

Re-sorts keys according to their times. Some MAXKey operations can result in out of order keys and this function must be called to correctly order keys. See the Controller Keys and Key Properties topic for MAXKey properties information.

createLockKey <controller> <time> <rot_or_pos_integer>

This method is called to create a locking key at the specified time. This is a key that looks back to the previous key and creates a new key at the specified time which matches the previous key in value. It also adjusts the parameters for the key such that the value stays constant from the previous key to this key. For instance, for a TCB controller the continuity of the previous key and new key will set to 0. For a Bezier controller the out tangent type of the previous key is set to linear and the in tangent type of the new key is set to linear.

If the controller passed to this method is a transform level controller, <rot_or_pos_integer> specifies whether to create the key in the transform controller's position or rotation (or roll angle) sub-controller. If rot_or_pos_integer = 0, the key is created in the position controller. For all other values, the key is created in the rotation (or roll angle) controller.

If the controller passed to this method is not a transform level controller, the <rot_or_pos_integer> value is not used.

Returns true if the key creation was successful, false otherwise.

The following script shows example usages of some of the above methods.

Example:

-- controller test bed 2

b=box height:10

at time 5 animate on b.height=50

at time 10 animate on b.height=100

bhc=b.height.controller

bhk=bhc.keys

addnewkey bhc 7

addnewkey bhc 9

for k in bhk do format "%:%\n" k.time k.value

selectKeys bhc (interval 7 9)

deleteKeys bhc #selection

bhk

addnewkey bhc 7

addnewkey bhc 9

selectKeys bhc (interval 7 9)

deleteKeys bhc #selection #slide

bhk

addnewkey bhc 7

addnewkey bhc 9

selectKeys bhc (interval 7 9)

deleteKeys bhc #selection #slide #rightToLeft

bhk

addnewkey bhc 8

i=getKeyIndex bhc 8

selectKey bhc i

moveKey bhc i 10

bhk

getKeyTime bhc 4

b.width.controller=noise_float()

numkeys b.width.controller


Controller Out-Of-Range Functions

getBeforeORT <controller>

Gets the Out-of-Range type (ORT) for the controller for the time before the first key. Returns one of the following name values:

#constant

#cycle

#loop

#pingPong

#linear

#relativeRepeat

getAfterORT <controller>

Gets the Out-of-Range (ORT) type for the controller for the time after the last key. Returns one of the name values as for getBeforeORT() shown above.

setBeforeORT <controller> <ORT_type_name>

Sets the Out-of-Range (ORT) type for the controller for the time before the first key. The <ORT_type_name> must be one of the following name values:

#constant

#cycle

#loop

#pingPong

#linear

#relativeRepeat

setAfterORT <controller> <ORT_type_name>

Sets the Out-of-Range (ORT) type for the controller for the time after the last key. The <ORT_type_name> must be one of the symbolic values shown in setBeforeORT() above. No testing done on the validity of <ORT_type_name> is performed.

enableORTs <controller> <boolean>

Enables or disables the Out-of-Range processing for the controller. If set to disabled with false, the controller effectively employs a constant ORT.


Controller Ease and Multiplier Curve Functions

addEaseCurve <controller> [ <float_controller> ]

Adds an ease curve to the specified controller. You may provide an optional float controller for the curve or have the function generate a default float controller for you. When you add a ease curve in Track View, keys are automatically created at the beginning and end of the current animation range. The addEaseCurve() method does not generate these keys, so you will need to add them to the ease curve controller.

deleteEaseCurve <controller> <index_integer>

Deletes the indexed ease curve from the controller. The indexes are 1-based and correspond to the order in which the curves were originally added to the controller.

numEaseCurves <controller>

Returns the number of ease curves currently operating on the controller.

applyEaseCurve <controller> <time>

Applies the combined ease curves in the specified controller to the given time value, returning the transformed time.

addMultiplierCurve <controller> [ <float_controller> ]

Adds a multiplier curve to the specified controller. You may provide an optional float controller for the curve or have the function generate a default float controller for you. When you add a ease curve in Track View, keys are automatically created at the beginning and end of the current animation range. The addMultiplierCurve() method does not generate these keys, so you will need to add them to the ease curve controller.

deleteMultiplierCurve <controller> <index_integer>

Deletes the indexed multiplier curve from the controller. The indexes are 1-based and correspond to the order in which the curves were originally added to the controller.

numMultiplierCurves <controller>

Returns the number of multiplier curves currently operating on the controller.

getMultiplierValue <controller> <time>

Returns the combined (float) value of the multiplier curves in the specified controller at the given time value.

Associated Properties

If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available:

<controller>.Ease_Curve -- the controller's ease curve value

If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available:

<controller>.Multiplier_Curve -- the controller's multiplier curve value

Notes

The values stored in an Ease Curve controller are stored as integer time ticks.

The following script shows example usages of some of the above methods.

Example:

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

reduceKeys <controller> <threshold> <step> [ <range> ]

where <threshold> is the closeness that the key-reduced controller will match the original keys, <step> is the time step at which the controller will be sampled and <range> is an optional time range within which the keys are reduced given as either 2 time values or an Interval value, defaulting to the active animation range.

Examples

reduceKeys $foo.pos.controller 0.5 1f

reduce keys on foo's position, retain 0.5 units accuracy, sample every frame.

reduceKeys $baz.bend.angle.controller 0.1 0.5f (interval 20 75)

Reduce keys on baz's bend angle, retain 0.1 units accuracy, sample every half frame, reduce within the interval 20f to 75f.

As with the reducer in the track view, a progress bar and cancel button is displayed.


Time and Key Functions on Object Hierarchies

Certain of the controller time and key functions can be called on any 3ds max object or collection of 3ds max objects, not just individual controllers. If called in this way, they apply recursively to all the nested controllers within those objects and on any on sub-objects and sub-controllers within those objects. In this way, they work in a manner similar to the object-level tracks in the 3ds max Track View that allow you to manipulate keys and time for all the sub-objects and sub-controllers within them.

The time and controller functions that work this way are:

deleteTime

reverseTime

scaleTime

insertTime

setTimeRange

addNewKey

deleteKeys

selectKeys

deselectKeys

moveKeys

sortKeys

reduceKeys

addEaseCurve

deleteEaseCurve

setBeforeORT

setAfterORT

enableORTs

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)


Controllers - Superclass Level

The following is a list of the controller superclasses:

FloatController

Matrix3Controller

MorphController

Point3Controller

PositionController

RotationController

ScaleController

QuatController

MasterBlockController


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

Bezier_Float

Block

Float_Expression

Float_List

Float_Motion_Capture

Float_Reactor

Float_Script

Linear_Float

LOD_Controller

Noise_Float

On_Off

SlaveFloat

TCB_Float

Waveform_Float


MasterBlockController : MAXWrapper

MasterBlockController is the superclass for the controllers associated with the Block Control Track View node. These classes are:

Block_Control

MasterBlock


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

Link_Transform

LookAt

PRS

IK_ControllerMatrix3Controller

Slave_Controller


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

Cubic_Morph_Controller


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

Bezier_Color

Bezier_Point3

Color_RGB

Noise_Point3

Point3_Expression

Point3_List

Point3_Motion_Capture

Point3_Reactor

Point3_Script

Point3_XYZ

Slave_Point3

TCB_Point3


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

Audioposition

Bezier_Position

Dynamic_Position_Controller

Linear_Position

Noise_Position

Path

Position_Expression

Position_List

Position_Motion_Capture

Position_Reactor

Position_Script

Position_XYZ

Surfaceposition

TCB_Position


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

Bezier_Rotation

Dynamics_Rotation_Controller

Euler_XYZ

Linear_Rotation

Local_Euler_XYZ

Noise_Rotation

Rotation_List

Rotation_Motion_Capture

Rotation_Reactor

Rotation_Script

SlaveRotation

TCB_Rotation


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

Bezier_Scale

Linear_Scale

Noise_Scale

Scale_Expression

Scale_List

Scale_Motion_Capture

Scale_Reactor

Scale_Script

ScaleXYZ

SlaveScale

TCB_Scale


QuatController : MAXWrapper

There are presently no classes associated with the QuatController superclass.


Attachment : PositionController

Constructor

attachment ...

Properties

<attachment>.keys : MAXKeyArray

<attachment>.node : Node

<attachment>.align : Boolean default: 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>.manupdate : Boolean default: false

Enables the update button.

Methods

AttachCtrl.getKey <attachment> <index_integer>

Returns the indexed key as a MAXAKey value

AttachCtrl.addNewKey <attachment> <time>

Returns the indexed key as a MAXAKey value

AttachCtrl.update <attachment>

Causes the controller to update if the manual update property is turned on for the attachment controller.

Notes

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

Attachment Controller Keys

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Attachment Controller Keys

Properties

For Attachment controller keys, the following properties are accessible:

<key>.time : Time (time value or number [interpreted as frames]) Read-only.

<key>.selected : Boolean

Specifies whether the key is selected. Read/write access.

The AttachCtrl.getKey() method returns keys of class MAXAKey. These keys have the following properties:

<MAXAKey>.face : Integer (0-based)

<MAXAKey>.coord : Point2 (barycentric coordinates)

<MAXAKey>.time : Time

<MAXAKey>.selected : Boolean

<MAXAKey>.tension : Float

<MAXAKey>.continuity : Float

<MAXAKey>.bias : Float

<MAXAKey>.easeTo : Float

<MAXAKey>.easeFrom : Float

See also

Key Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Barycentric_Morph_Controller : MorphController

You access the morph controller on a morph compound object via the <node>.morph property, for example:

c = $foo.morph -- get the morph controller

mk1 = c.keys[1] -- get the first morph key

Constructor

createMorphObject <source_node>

Turns the given scene node into a Morph compound object - does nothing if it already is a Morph object. The returned morph object has a morph controller created accessible via the morph property.

Methods

addMorphTarget <morph_controller> <target_node> <add_method>

Adds a new morph target object to the given morph controller. The <add_method> argument defines the method of attaching the target and should be a number between 1 and 4 with the following interpretation:

1 -- by reference

2 -- by copy

3 -- by move

4 -- by instance

The return value is an Integer giving the target index of the added target object.

setMorphTarget <morph_controller> <target_index_integer> <target_node> <add_method>

Replaces an existing target with a different scene node. The arguments are the same as for addMorphTarget().

getMKTargetNames <morph_controller>

Returns an array of names of the targets in the given morph controller.

deleteMorphTarget <morph_controller> <target_index_integer>

Deletes the numbered morph target in the given controller.

setMorphTargetName <morph_controller> <target_index_integer> <name_string>

Changes the target name of the numbered target in the given morph controller.

getMKTargetWeights <morph_controller> <time> <dest_array>

A quick way of retrieving all the target weights for a given key at the time specified. The targets are placed into <dest_array> which must be an array of the right size. You can find out how many targets there by getting the size of the array returned by the getMKTargetNames() function which returns an array of target names.

getMKKey <morph_controller> <time>

Returns the morph key on the given controller at the specified time, yields undefined if there is no key at that time.

getMKKeyIndex <morph_controller> <time>

Returns the index of the key at the specified time, yields undefined if there is no key at that time.

Notes

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

Barycentric_Morph_Controller Keys

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Barycentric_Morph_Controller Keys

Note: This class is not available in 3D Studio VIZ.

The morph key functions operate on MAXScript key values that are accessed on Barycentric morph controllers in the same way as keys on other keyable controllers. For Barycentric_Morph_Controller keys, the following properties and methods are accessible:

Properties

<key>.time Time -- time value or number (interpreted as frames). Read-only.

<key>.selected Boolean -- specifies whether the key is selected. Read/write access.

Methods

getMKTime <morph_key>

Returns the given morph key's time.

setMKTime <morph_key> <time>

Sets the time of the given morph key.

getMKWeight <morph_key> <target_index_integer>

Gets the weight as a percentage for the numbered target on the given morph key. Targets are numbered in order as seen in the target list in the morph key Track View dialog. This is the order in which the targets were added.

setMKWeight <morph_key> <target_index_integer> <pcnt_float> <keep100%_boolean>

Sets the percentage weight of the numbered target on the given morph key. The last argument is a boolean, if true adjusts other target weights so the maximum is 100%.

Notes

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.

Script:

sel1 = sphere radius:30 -- target 1

sel2 = sphere radius:50 -- target 2

createMorphObject sel1 -- create the morph object from sel1

mobj1= sel1.morph -- grab morph controller

addmorphtarget mobj1 sel2 3 -- add sel2 as target - creates key with

-- target weights of 0 and 100%

k=mobj1.keys[1] -- grab the key

setMKWeight k 1 100 true -- set target 1 to 100%, keep total 100%

addnewkey mobj1 50 -- create morph key at frame 50

k=getMKKey mobj1 50 -- grab the key

setMKWeight k 2 100 true -- set target 2 to 100%, keep total 100%

Output:

$Sphere:Sphere01 @ [0.0,0.0,0.0] -- result line 1

$Sphere:Sphere02 @ [0.0,0.0,0.0] -- result line 2

$Editable_Mesh:Sphere01 @ [0.0,0.0,0.0] -- result line 3

Controller:Barycentric_Morph_Controller -- result line 4

2 -- result line 5

#Barycentric Morph Controller key(1 @ 0f) -- result line 7

1 -- result line 8

#Barycentric Morph Controller key(0 @ 50f) -- result line 9

#Barycentric Morph Controller key(2 @ 50f) -- result line 10

2

See also

Key Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Bezier Controllers

bezier_color : point3Controller
bezier_float : floatController
bezier_point3 : point3Controller
bezier_position : positionController
bezier_rotation : rotationController
bezier_scale : scaleController

Constructor

bezier_color ...

bezier_float ...

bezier_point3 ...

bezier_position ...

bezier_rotation ...

bezier_scale ...

Properties

<bezier_controller>.keys MAXKeyArray

See also

MAXKeyArray Values

Bezier Controller Keys

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Bezier Controller Keys

For Bezier controller keys, the following properties are accessible:

Properties

<key>.time Time -- time value or number (interpreted as frames)

<key>.selected Boolean -- specifies whether the key is selected

<key>.value varies -- class determined by its containing controller

<key>.inTangent varies -- float or point3 (see below)

<key>.outTangent varies -- float or point3 (see below)

<key>.inTangentType Name -- see list of permitted names below

<key>.outTangentType Name -- see list of permitted names below

<key>.x_locked Boolean default: true

<key>.y_locked Boolean default: true

<key>.z_locked Boolean default: true

<key>.constantVelocity Boolean default: false

The inTangent and outTangent values are Floats in keys of float controllers and Point3s for the other appropriate controllers. Default value is 0 for float controllers, [0,0,0] otherwise.

The inTangentType and outTangentType properties have symbolic name values representing the 6 possible tangent types available in the drop-down menu in the Bezier key property dialog:

#smooth (default)

#linear

#step

#fast

#slow

#custom

Examples:

c = bezier_position () -- create and assign new controller

$bar.pos.controller = c

k = addNewKey c 0f -- add a key at frame 0

k.value = [10,0,0] -- set value there

k.outTangentType = #slow -- and outgoing tangent type

k = addNewKey c 100f -- add another key at 100

k.value = [200,10,0] -- set value

k.inTangentType = #custom -- make inTangent custom

k.inTangent = [0.2, 0.02, 0.112] -- set its tangents

k.x_locked = false -- and unlock handles

See also

Key Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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 MasterBlock : MasterBlockController for more information.

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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 MasterBlock : MasterBlockController for more information.

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Cubic_Morph_Controller : MorphController

The Barycentric_Morph_Controller should be used instead of a Cubic_Morph_Controller controller.

Constructor

Cubic_Morph_Controller ...

Note: This class is not available in 3D Studio VIZ.

Properties

<Cubic_Morph_Controller>.keys MAXKeyArray

See also

MAXKeyArray Values

Cubic_Morph_Controller Keys

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Cubic_Morph_Controller Keys

Properties

For Cubic_Morph_Controller keys, the following properties are accessible:

<key>.time Time -- time value or number (interpreted as frames). Read-only.

<key>.selected Boolean -- specifies whether the key is selected. Read/write access.

See also

Key Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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.

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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.

All the IK-related methods are in the ik structure and are associated with a parameter in the Motion panel, IK Controller Parameters rollout. These functions return undefined if executed on an object whose controller is not an IK controller. The controller actually being accessed in these methods is the master IK controller. Accessing the IK controller for any object in the IK system accesses the same master IK controller.

Note:

The following ik structure methods are still present, but not applicable in 3ds max 4. Getting/setting via these methods return a value of 'undefined':

GetRotThreshold
SetRotThreshold
GetPosThreshold
SetPosThreshold
GetIterations
SetIterations

ik.GetPosThreshold <node>

ik.SetPosThreshold <node> <float>

Get and set the Position threshold value for the specified object.

ik.GetRotThreshold <node>

ik.SetPosThreshold <node> <float>

Get and set the Rotation threshold value for the specified object.

ik.GetIterations <node>

ik.SetIterations <node> <integer>

Get and set the Iterations value for the specified object.

ik.GetStartTime <node>

ik.SetStartTime <node> <time>

Get and set the Start time for the specified object

ik.GetEndTime <node>

ik.SetEndTime <node> <time>

Get and set the End time for the specified object

ik.getPinNode <node>

Gets the node the specified node is bound to in the IK panel as a <node> value, undefined if none.

ik.setPinNode <node> (<node> | undefined)

Sets the node the specified node is bound to in the IK panel. If undefined is specified, the node is unbound. Returns true if the bind was successful, false otherwise.

ik.getPrecedence <node>

Gets the precedence of the node as specified in the IK panel as an <integer> value

ik.setPrecedence <node> <number>

Sets the precedence of the node as specified in the IK panel. Returns true if the assignment was successful, false otherwise.

ik.getIsTerminator <node>

ik.setIsTerminator <node> <boolean>

Get/set whether the node is a terminator.

ik.getBindPos <node>

ik.setBindPos <node> <boolean>

Get/set whether Bind Position is turned on for the node.

ik.getBindOrient <node>

ik.setBindOrient <node> <boolean>

Get/set whether Bind Orientation is turned on for the node.


Linear Controllers

linear_float : floatController
linear_position : positionController
linear_rotation : rotationController
linear_scale : scaleController

Constructor

linear_float ...

linear_position ...

linear_rotation ...

linear_scale ...

Properties

<controller>.keys MAXKeyArray

See also

MAXKeyArray Values

Linear Controller Keys

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Linear Controller Keys

For Linear controller keys, the following properties are accessible:

Properties

<key>.time Time -- time value or number (interpreted as frames)

<key>.selected Boolean -- specifies whether the key is selected

<key>.value varies -- class determined by its containing controller

See also

Key Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Link_Control : Matrix3Controller

Constructor

link_control ...

Properties

<link_control>.transform Matrix3Controller

Contains the transform controller below the link controller

Methods

linkCtrl.getLinkCount <link_control>

Returns the number of nodes linked to as an integer.

linkCtrl.getLinkNode <link_control> <index_integer>

Returns the node for the indexed link as a node value.

linkCtrl.setLinkNode <link_control> <index_integer> <node>

Sets the node for the indexed link. The indexed link must already exist.

linkCtrl.getLinkTime <link_control> <index_integer>

Returns the time for the indexed link as a time value.

linkCtrl.setLinkTime <link_control> <index_integer> <time>

Sets the time for the indexed link. The indexed link must already exist.

linkCtrl.addLink <link_control> <node> <time>

Adds the specified node as a link with the specified time.

linkCtrl.deleteLink <link_control> <index_integer>

Deletes the indexed link.

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


List Controllers

float_list : floatController
point3_list : point3Controller
position_list : positionController
rotation_list : rotationController
scale_list : scaleController

Constructor

float_list ...

point3_list ...

position_list ...

rotation_list ...

scale_list ...

Properties

The property list for a list controller contains the sub-controllers in the list controller (if any), plus an available property. The available property has a controller property, which contains a "phantom" controller. To add a controller to a list controller, assign the controller to the available.controller property. The following script shows an example of creating and adding controllers to a list controller.

Script:

p=float_list() -- create a list controller

showproperties p -- show its properties

p.available.controller -- the "phantom" controller

p1=bezier_float() -- create a new bezier float controller

p.available.controller=p1 -- add it to the list controller

p2=bezier_float() -- create a new bezier float controller

p.available.controller=p2 -- add it to the list controller

getpropnames p -- show the list controller properties

showproperties p -- show the list controller properties

p.numSubs -- the number of list controller subAnims

getsubanimnames p -- show the list controller subAnim names

p[2].object -- retrieve the second bezier float controller

Output:

Controller:Float_List -- result line 1

.available : float -- output line 2

OK -- result line 2

Controller: -- result line 3 (the "phantom" controller)

Controller:Bezier_Float -- result line 4

Controller:Bezier_Float -- result line 5

Controller:Bezier_Float -- result line 6

Controller:Bezier_Float -- result line 7

#(#bezier_float, #available) -- result line 8

.bezier_float : float -- output line 9

.bezier_float : float -- output line 9

.available : float -- output line 9

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.

Example:

-- creates new list controller from old, deleting indexed controller

-- returns the new controller

fn deleteFromListController list_cont index =

(

-- create new list controller based on class of input list controller

new_cont=execute ((classof list_cont as string) + "()")

-- for each subAnim (except the last, which is the phantom "available"

-- controller)..

for i=1 to (list_cont.numSubs-1) do

-- if not the sub-controller to delete

if i != index do

-- instance the sub-controller (contained in the .object property of

-- the subAnim) to the new list controller

new_cont.available.controller=list_cont[i].object

-- and return the new list controller

return new_cont

)

--

-- example usage (obj.pos already has list controller)

obj.pos.controller = deleteFromListController obj.pos.controller 2

Methods

listCtrl.getName <list_controller> <index_integer>

Returns the name of the indexed subcontroller in the list controller

listCtrl.setName <list_controller> <index_integer> <string>

Sets the name of the indexed subcontroller in the list controller. If the string is a null string (""), the default controller name is used.

listCtrl.getActive <list_controller>

Returns the index of the active subcontroller in the list controller

listCtrl.setActive <list_controller> <index_integer>

Sets the indexed subcontroller in the list controller as the active controller

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


LookAt : Matrix3Controller

Constructor

lookat ...

Properties

<lookAt>.position Bezier_Position -- the position controller

<lookAt>.roll_angle Bezier_Float -- the roll controller

<lookAt>.scale Bezier_Scale -- the scale controller

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

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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:

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Noise Controllers

noise_float : floatController
noise_point3 : point3Controller
noise_position : positionController
noise_rotation : rotationController
noise_scale : scaleController

Constructor

noise_float ...

noise_point3 ...

noise_position ...

noise_rotation ...

noise_scale ...

Properties

Access to the following properties is available on all noise controllers:

<noise_controller>.seed Integer default: 0

<noise_controller>.frequency Float default: 0.5

<noise_controller>.fractal Boolean default: true

<noise_controller>.roughness Float default: 0.0

<noise_controller>.rampin Time default: 0f

<noise_controller>.rampout Time default: 0f

In addition, for noise float controllers you can get these properties:

<noise_controller>.noise_strength Float default: 50 -- animatable

<noise_controller>.positive Boolean default: false

limits values to > 0

and for noise position, point3, rotation and scale controllers:

<noise_controller>.noise_strength Point3 default: varies -- animatable

position and point3 default: [50,50,50]

rotation default: [0.785398,0.785398,0.785398]

scale default: [0.5,0.5,0.5]

<noise_controller>.x_positive Boolean default: false

<noise_controller>.y_positive Boolean default: false

<noise_controller>.z_positive Boolean default: false

limits values to > 0

Notes

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


On_Off : FloatController

Constructor

on_off ...

Properties

<on_off>.keys MAXKeyArray

See also

MAXKeyArray Values

On_Off Controller Keys

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


On_Off Controller Keys

Properties

For On_Off keys, the following properties are accessible:

<key>.time Time -- time value or number (interpreted as frames). Read-only.

<key>.selected Boolean -- specifies whether the key is selected. Read/write access.

See also

Key Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Path : PositionController

Constructor

path ...

Properties

<path>.allowUpsideDown Boolean default: false -- alias: Allow_Upside_Down

Turn on to avoid the situation in which an object flips when going around a vertically oriented path.

<path>.axis Integer default: 0

axis = 0 - X; 1 - Y; 2 - Z

<path>.axisFlip Boolean default: false -- alias: Axis_Flip

Flips the direction of the object on the path 180 degrees.

<path>.bank Boolean default: false

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

<path>.bankAmount Float default: 0.5 -- animatable, alias: Bank_Amount

The amount of the banking to one side or the other, depending on whether the value is positive or negative.

<path>.constantVel Boolean default: false -- alias: Constant_Velocity

Provides a constant velocity along the path. When off, the velocity of the object along the path varies depending on the distance between the vertices on the path.

<path>.follow Boolean default: 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 Float default: 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.

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

Example:

thePath=circle radius:50 -- create shape node for path

theObj=cone radius1:6 radius2:0 height:15 -- create object to travel on path

theObj.pos.controller=path follow:true -- assign path controller to object

PosCont=theObj.pos.controller -- grab the path controller

PosCont.path=thePath -- set path to shape node

PosCont.axis=2 -- point local Z axis along path

animate on -- create keys at…

(

at time 30 PosCont.percent=25 -- frame 30 - 25% along path

at time 100 PosCont.percent=95 -- frame 100 - 95% along path

)

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


PRS : Matrix3Controller

Constructor

prs ...

Properties

<prs>.position Bezier_Position -- the position controller

<prs>.rotation TCB_Rotation -- the rotation controller

<prs>.scale Bezier_Scale -- the scale controller

Notes

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.

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Reactor Controllers

float_Reactor : floatController
point3_Reactor : point3Controller
position_Reactor : positionController
rotation_Reactor : rotationController
scale_Reactor : scaleController

Constructor

float_Reactor ...

point3_Reactor ...

position_Reactor ...

rotation_Reactor ...

scale_Reactor ...

Methods

createReaction <reactor_controller>

Creates a new reaction for the specified reactor controller.

deleteReaction <reactor_controller> <index_integer>

Deletes the specified reaction. <index_integer> is the reaction you want to delete. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

reactTo <reactor_controller> ( <controller> | <node> )

Sets the controller that the reactor controller reacts to. You can either specify either a controller you want to react to or a node whose world position to react to.

getReactionCount <reactor_controller>

Returns the number of reactions for the specified reactor controller.

selectReaction <reactor_controller> <index_integer>

Selects the specified reaction. <index_integer> is the reaction you want to select. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

getSelectedReactionNum <reactor_controller>

Returns the number of the selected reaction.

getReactionFalloff <reactor_controller> <index_integer>

Returns the specified reaction's falloff. <index_integer> is the reaction you want to get the falloff from. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

setReactionFalloff <reactor_controller> <index_integer> <float>

Sets the specified reaction's falloff to the specified value. <index_integer> is the reaction you want to set the falloff for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

getReactionInfluence <reactor_controller> <index_integer>

Returns the specified reaction's influence. <index_integer> is the reaction you want to get the influence from. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

setReactionInfluence <reactor_controller> <index_integer> <float>

Sets the specified reaction's influence to the specified value. <index_integer> is the reaction you want to set the influence for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

getReactionStrength <reactor_controller> <index_integer>

Returns the specified reaction's strength. <index_integer> is the reaction you want to get the strength from. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

setReactionStrength <reactor_controller> <index_integer> <float>

Sets the specified reaction's strength to the specified value. <index_integer> is the reaction you want to set the strength for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

getReactionState <reactor_controller> <index_integer>

Returns the specified reaction's state. The value type returned matches the reactor controller type. <index_integer> is the reaction you want to get the state from. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

setReactionState <reactor_controller> <index_integer> <value>

Sets the specified reaction's state to the specified value. <index_integer> is the reaction you want to set the state for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in. The <value> type must match the reactor controller type.

getReactionValue <reactor_controller> <index_integer>

Returns the specified reaction's value. The return value type is the same as the controller type being reacted to. <index_integer> is the reaction you want to get the value from. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

setReactionValue <reactor_controller> <index_integer> <value>

Sets the specified reaction's value to the specified value. <index_integer> is the reaction you want to set the value for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in. The <value> type must match the controller type being reacted to.

setReactionName <reactor_controller> <index_integer> <string>

Sets the name of the specified reaction. <index_integer> is the reaction you want to set the name for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in.

getReactionName <reactor_controller> <which>

Returns the specified reaction's name. <index_integer> is the reaction you want to get the name of. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

Example:

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

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Script controllers function in similar way to expression controllers, providing a properties dialog in which a script can be entered that is used to compute the controller value. The primary advantages of script controllers are:

  • They can use all the features of the MAXScript language including loops, scripted functions, pathnames, etc.

  • Almost any property of any object in the scene can be used to help compute controller values, including things like mesh vertices, values of properties at arbitrary frame times, and other non-animatable properties that are not accessible in Expression controllers.

  • They can use MAXScript global variables to communicate and coordinate with other controllers and scripts in 3ds max.

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.

Writing Controller Scripts

3ds max interprets the text you type into the Script text box as the body of a MAXScript block expression, so you can type as many expressions as you want on as many lines as you want and they are evaluated in turn and the value of the last expression is taken as the controller value. This value must yield the right type for the controller, Float for float, Point3 for position, Quat for rotation, etc.

The value returned from a script controller may not necessarily be the same value seen in Track View or in the command panels, nor the same value returned by accessing the property value in MAXScript. Part of a MAXWrapper property definition is a scaling value that is applied when reading or setting the true value stored in a controller. For example, the slice_to and slice_from properties associated with many of the geometry primitives is displayed in degrees. The actual value stored in the controller associated with these properties are in radians. This scaling factor is an internal property of the MAXWrapper property, and not an internal property of the controller. Both 3ds max and MAXScript automatically apply the specified scaling factor when accessing properties, so this scaling is normally invisible to the user. The exception is when script or expression controllers are used. For these controllers, the data value returned must be the unscaled value, as 3ds max will then apply the scaling factor to the output value. In the documentation of the MAXWrapper classes, any scaling applied to a property is shown. If there is no scaling listed, no scaling occurs for that property. For example, a portion of the Capsule documentation is:

<Capsule>.radius Float default: 0.0 -- animatable

<Capsule>.height Float default: 0.0 -- animatable

<Capsule>.slice_from Float default: 0.0 -- animatable, angle

<Capsule>.slice_to Float default: 0.0 -- animatable, angle

From this, a scripted controller would return unscaled values for the radius and height properties, and radians for slice_from and slice_to. The scaling types, stored value meaning, and scaling value applied to the true controller value are as follows:

Angle -- value stored in radians, output scaled by 57.29578

Percentage -- value stored as fraction (0 to 1), output scaled by 100

For properties that have a Color value type, the controller output is automatically scaled by 255. If a point3_script is assigned to one of these properties, each component value should stored as fraction (0 to 1). Remember that converting a MAXScript Color value to a Point3 value does not apply a scaling factor – red as point3 returns a value of [255,0,0]. Therefore you must explicitly scale a Color value by dividing by 255 if it is output by the script controller.

The body of a script controller's script is any valid MAXScript expression that evaluates to the proper data type, and can contain global and local variables, functions, and structure definitions. The script is compiled in its own local scope, and the locals are only visible inside the scope of the script controller. Script controller local variables are heap-based locals, which are slightly different from normal (stack-based) locals. Normal locals are visible in the current scope and have a lifetime of one execution of that scope. Heap-based locals are also visible only in the current scope, but have a lifetime equal to the lifetime of the top-level expression where they are defined. A script controller's locals are created the first time the script is executed and are kept permanently in the heap (unless 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 Scope of Variables 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.

Example:

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

Example:

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

Limitations

Script controllers are not automatically updated when you interactively modify objects that they depend on.

If you move the time slider or if you animate the changes and then play the animation, the changes are reflected automatically. Because the scripts can refer to other objects in very indirect ways or conditional ways, it is not possible for MAXScript to automatically determine the objects a script depends on.


Slave_Control : Matrix3Controller

Note: This class is not available in 3D Studio VIZ.

The Slave_Control is used as the transform controller for the boxes in a RingArray system object. You cannot create a RingArray system using MAXScript in 3ds max 4, but properties for this controller are accessible by MAXScript for existing RingArray systems. A RingArray system actually consists of two types of controllers – the master controller and Slave_Control controllers. The Slave_Control controllers are used as the transform controller for all the boxes in the RingArray system, and the master controller controls the individual Slave_Control controllers. Changing a property value for one Slave_Control in a RingArray system changes the property value for all Slave_Controls in the system.

Properties

<Slave_Control>.radius Float default: 100.0 -- animatable

<Slave_Control>.cycles Float default: 3.0 -- animatable

<Slave_Control>.amplitude Float default: 20.0 -- animatable

<Slave_Control>.phase Float default: 1.0 -- animatable


Slave Controllers

slavefloat : floatController
slave_point3 : point3Controller
slavepos : positionController
slaverotation : rotationController
slavescale : scaleController

Constructor

The Slave controllers are not creatable by MAXScript. They can only be created by creating a Masterblock in the Block Control node in the Global Tracks node of Track View. See MasterBlock : MasterBlockController for more information.

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


SurfacePositionController : PositionController

Surface_position : PositionController

Constructor

Surface_position ...

Properties

<Surface_position>.surface Node default: undefined

<Surface_position>.u Float default: 0.0 -- animatable

<Surface_position>.v Float default: 0.0 -- animatable

<Surface_position>.align Integer default: 1

align = 1 - No Alignment; 2 - Align to U; 3 - Align to V

<Surface_position>.flip Boolean default: false

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


TCB Controllers

TCB_float : floatController
TCB_point3 : point3Controller
TCB_position : positionController
TCB_rotation : rotationController
TCB_scale : scaleController

Constructor

TCB_float ...

TCB_point3 ...

TCB_position ...

TCB_rotation ...

TCB_scale ...

Properties

<controller>.keys MAXKeyArray

See also

MAXKeyArray Values

TCB Controller Keys

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


TCB Controller Keys

For TCB controller keys, the following additional properties are accessible:

<key>.time Time -- time value or number (interpreted as frames)

<key>.selected Boolean -- specifies whether the key is selected

<key>.value varies -- class determined by its containing controller

<key>.tension Float default: 25.0

<key>.continuity Float default: 25.0

<key>.bias Float default: 25.0

<key>.easeTo Float default: 0.0

<key>.easeFrom Float default: 0.0

See also

Key Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


XYZ Controllers

Color_RGB : Point3Controller
Euler_XYZ : RotationController
Local_Euler_XYZ : RotationController
Point3_XYZ : Point3Controller
Position_XYZ : PositionController
ScaleXYZ : ScaleController

Constructor

Color_RGB ...

Euler_XYZ ...

Local_Euler_XYZ ...

Point3_XYZ ...

Position_XYZ ...

ScaleXYZ ...

Properties

The property names for the XYZ controllers vary between the specific controllers.

Color_RGB:

<Color_RGB>.r Float default: 0.0 -- animatable

<Color_RGB>.g Float default: 0.0 -- animatable

<Color_RGB>.b Float default: 0.0 -- animatable

Euler_XYZ:

<Euler_XYZ>.x_rotation Float default: 0.0 -- animatable

<Euler_XYZ>.y_rotation Float default: 0.0 -- animatable

<Euler_XYZ>.z_rotation Float default: 0.0 -- animatable

<Euler_XYZ>.axisOrder Integer default: 1

Get/set the order of application of the axis angles. Its value can be any of the following:

1 - XYZ

2 - XZY

3 - YZX

4 - YXZ

5 - ZXY

6 - ZYX

7 - XYX

8 - YZY

9 - ZXZ Local_Euler_XYZ:

<Local_Euler_XYZ>.local_x_rotation Float default: 0.0 -- animatable

<Local_Euler_XYZ>.local_y_rotation Float default: 0.0 -- animatable

<Local_Euler_XYZ>.local_z_rotation Float default: 0.0 -- animatable

<Local_Euler_XYZ>.axisOrder Integer default: 1

Get/set the order of application of the axis angles. Its value can be any of the following:

1 - XYZ

2 - XZY

3 - YZX

4 - YXZ

5 - ZXY

6 - ZYX

7 - XYX

8 - YZY

9 - ZXZ Point3_XYZ:

<Point3_XYZ>.x Float default: 0.0 -- animatable

<Point3_XYZ>.y Float default: 0.0 -- animatable

<Point3_XYZ>.z Float default: 0.0 -- animatable

Position_XYZ:

<Position_XYZ>.x_position Float default: 0.0 -- animatable

<Position_XYZ>.y_position Float default: 0.0 -- animatable

<Position_XYZ>.z_position Float default: 0.0 -- animatable

ScaleXYZ:

<ScaleXYZ>.x_scale Float default: 0.0 -- animatable

<ScaleXYZ>.y_scale Float default: 0.0 -- animatable

<ScaleXYZ>.z_scale Float default: 0.0 -- animatable

Methods

getXYZControllers <controller>

Returns an array of the X, Y, and Z sub-controllers of the specified controller

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Atmospheric : MAXWrapper

The Atmospheric class lets you set up volumetric rendering effects with MAXScript. You can create atmospherics like fire 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 Atmospheric Effect Types.

The properties, operators, and methods that are common to all classes derived directly from the Atmospheric class are described in Atmospheric Effects Common Properties, Operators, and Methods.

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 MAXWrapper Common Properties, Operators, and Methods.


Atmospheric Effects Common Properties, Operators, and Methods

Atmospherics have the following common properties and methods:

Properties

<atmos>.name String default: varies

The name as it appears in the Environment dialog list. The class name is used as the default name when no name: creation parameter is supplied.

<atmos>.numGizmo Integer -- read-only

The number of gizmos ever assigned to the atmospheric. A gizmo obtained via .getGizmo 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. numGizmo is the size of the array, not the number of used slots.

Methods

isActive <atmos>

Returns true if the atmospheric is set to active; false otherwise.

getGizmo <atmos> <index_integer>

Retrieves the indexed gizmo node from the atmospheric. The gizmo node will be a light or atmospheric helper. The Index is 1-based.

deleteGizmo <atmos> <index_integer>

Deletes the indexed gizmo from the atmospheric.

appendGizmo <atmos> <node>

Appends the node to the gizmo list on the atmospheric. It must be of the right kind for the atmospheric, lights for volumeLights, helper gizmos for fire_effect, etc.

setActive <atmos> <boolean>

Sets the atmospheric active or inactive. If <boolean> is true the atmospheric is set to active; if false, inactive.

Associated Methods

You can use the following functions for maintaining the list of atmospherics in the global rendering environment:

addAtmospheric <atmos>

Appends the atmospheric to the Atmospheric Effects list

getAtmospheric <index_integer>

Retrieves the atmospheric at the indexed position in the Atmospheric Effects list. Index is 1-based.

setAtmospheric <index_integer> <atmos>

Sets the atmospheric at the indexed position in the Atmospheric Effects list to the specified atmospheric. If the Atmospheric Effects dialog is displayed when this method is called, the displayed Atmospheric Effects list is not updated.

deleteAtmospheric <index_integer>

Deletes the atmospheric at the indexed position in the Atmospheric Effects list. Index is 1-based.

editAtmosphere <atmos> <node>

Opens the Environment dialog, and opens the rollout for the specified atmospheric if it has been added to the Atmospheric Effects list. If the specified node is a gizmo for the atmospheric, that gizmo is selected in the atmospheric's gizmo list.

editAtmospheric <atmos> [ gizmo: <node> ]

Opens the Environment dialog, and opens the rollout for the specified atmospheric if it has been added to the Atmospheric Effects list. If the optional gizmo: argument is specified, and the specified node is a gizmo for the atmospheric, that gizmo is selected in the atmospheric's gizmo list.

The 3ds max global variable numAtmospherics gives you the number of current atmospherics in the rendering environment.

Notes

Unlike most MAXWrapper objects, you can not copy an Atmospheric.

See also

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

Example

atmos = fire_effect density:20 outer_color:red

appendGizmo atmos $SphereGizmo01


Atmospheric Effect Types

The following list shows the 3ds max Atmospheric Effect types:

Fire_Effect

Fog

Volume_Fog

Volume_Light


Fire_Effect : Atmospheric

Constructor

Fire_Effect ...

Properties

<Fire_Effect>.Inner_Color Color default: (color 252 202 0) -- animatable

Sets the color of the densest part of the effect. For a typical fire, this color represents the hottest part of the flame.

<Fire_Effect>.Outer_Color Color default: (color 225 30 30) -- animatable

Sets the color of the sparsest part of the effect. For a typical fire, this color represents the cooler, dissipating edge of the flame. The fire effect is colored using a gradient between the inner and outer colors. The dense areas of the effect use the inner color and gradually blend to the outer color near the edges of the effect.

<Fire_Effect>.Smoke_Color Color default: (color 25.5 25.5 25.5) -- animatable

Sets the color of smoke for use with the Explosion option.

<Fire_Effect>.Flame_Type Integer default: 0

Sets the flame type:

0- Fire Ball (Creates round puffy flames. Fireballs are well suited for explosions.)

1- Tendril (Creates directional pointed flames with veins along their center. The flames orient along the local Z axis of the fire apparatus. Tendril creates campfire-like flames.)

<Fire_Effect>.Stretch Float default: 1.0 -- animatable

Scales flames along the Z axis of the apparatus. Stretch works best with Tendril flames, but you can use it to give Fireballs an oval shape. Values less than 1.0 compress flames, making them shorter and thicker. Values greater than 1.0 stretch flames, making them long and skinny.

<Fire_Effect>.Regularity Float default: 0.2 -- animatable

Modifies how the flames fill the apparatus. A value of 1.0 completely fills the apparatus. The effect fades near the edges of the apparatus, but the overall shape is still very noticeable. A value of 0.0 produces a very irregular effect that might occasionally reach the boundary of the apparatus, but usually gets trimmed back and is smaller.

<Fire_Effect>.Flame_Size Float default: 35.0 -- animatable

Sets the size of individual flames inside the apparatus. The size of the apparatus affects the flame size. A larger apparatus requires a larger flame size. Use a range from 15.0 to 30.0 for the best results. Large values work best for Fireballs. Small values work best for Tendrils.

<Fire_Effect>.Flame_Detail Float default: 3.0 -- animatable

Controls the amount of color change and edge sharpness seen within each flame. Low values produce smooth, fuzzy flames and render faster. High values produce patterned, sharp flames and render slower.

<Fire_Effect>.Density Float default: 15.0 -- animatable

Sets the opacity and brightness of the fire effect. The size of the apparatus affects the density. A large apparatus with the same density as a small apparatus appears more opaque and brighter because of its larger size. Low values make the effect less opaque and use more of the outer color. High values make the effect more opaque and brighten the effect by gradually replacing the inner color with white. The higher the value, the more white the center of the effect is.

<Fire_Effect>.Samples Integer default: 15 -- animatable

Sets the rate at which the effect is sampled. Higher values produce more accurate results but take longer to render.

<Fire_Effect>.phase Float default: 0.0 -- animatable

Controls the rate of change for the fire effect.

<Fire_Effect>.Drift Float default: 0.0 -- animatable

Sets how flames are rendered along the Z-axis of the fire apparatus. The value is the amount of rise in units.

<Fire_Effect>.Explosion Integer default: 0

When on, animates size, density, and color automatically based on the animation of the phase value.

0- Off

1- On

<Fire_Effect>.Smoke Integer default: 1

Controls whether or not the explosion creates smoke.

0- Off

1- On

<Fire_Effect>.Fury Float default: 1.0

Varies the churning effect of the Phase parameter. Values greater than 1.0 cause faster churning. Values less than 1.0 cause slower churning.

Notes

The Explosion, Smoke, and Fury properties are not available in 3D Studio VIZ.

See also

Atmospheric Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

-- add key 2 at 75 & set

k = addNewKey pc 75

k.value = 300

k.inTangentType = #slow

k.outTangentType = #fast

-- or, to change times if the keys are already there:

c.phase.keys[1].time = 20

c.phase.keys[2].time = 75


Fog : Atmospheric

Constructor

fog ...

Properties

<Fog>.Fog_Color Color default: (color 255 255 255) -- animatable

<Fog>.Use_Color_Map Integer default: 0

Use_Color_Map = 0 - off; 1 - on

<Fog>.Use_Opacity_Map Integer default: 0

Use_Opacity_Map = 0 - off; 1 - on

<Fog>.Fog_Background Integer default: 1

Fog_Background = 0 - off; 1 - on

<Fog>.Fog_Type Integer default: 0

Fog_Type = 0 - Standard; 1 - Layered

<Fog>.Exponential Integer default: 0

Exponential = 0 - off; 1 - on

<Fog>.Near Float default: 0.0 -- animatable, percentage

<Fog>.Far Float default: 100.0 -- animatable, percentage

<Fog>.Top Float default: 100.0 -- animatable

<Fog>.Bottom Float default: 0.0 -- animatable

<Fog>.Density Float default: 50.0 -- animatable

<Fog>.falloff Integer default: 2

falloff = 0 - Top; 1 - Bottom; 2 - None

<Fog>.Horizon_Noise Integer default: 0

Horizon_Noise = 0 - off; 1 - on

<Fog>.size Float default: 20.0 -- animatable

<Fog>.angle Float default: 5.0 -- animatable, angle

<Fog>.phase Float default: 0.0 -- animatable

Notes

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.

See also

Atmospheric Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Volume_Fog : Atmospheric

Constructor

volume_fog ...

Properties

<Volume_Fog>.Soften_Gizmo_Edges Float default: 0.2 -- animatable

<Volume_Fog>.Fog_Color Color default: (color 255 255 255) -- animatable

<Volume_Fog>.Exponential Integer default: 0

Exponential = 0 - off; 1 - on

<Volume_Fog>.Density Float default: 20.0 -- animatable

<Volume_Fog>.Step_Size Float default: 4.0

<Volume_Fog>.Max_Steps Integer default: 100

<Volume_Fog>.Fog_Background Integer default: 1

Fog_Background = 0 - off; 1 - on

<Volume_Fog>.Noise_Type Integer default: 0

Noise_Type = 0 - Regular; 1 - Fractal; 2 - Turbulence

<Volume_Fog>.invert Integer default: 0

invert = 0 - off; 1 - on

<Volume_Fog>.High_Threshold Float default: 1.0 -- animatable

<Volume_Fog>.Low_Threshold Float default: 0.0 -- animatable

<Volume_Fog>.Uniformity Float default: 0.0 -- animatable

<Volume_Fog>.Levels Float default: 3.0 -- animatable

<Volume_Fog>.size Float default: 20.0 -- animatable

<Volume_Fog>.phase Float default: 0.0 -- animatable

<Volume_Fog>.Wind_Strength Float default: 0.0

<Volume_Fog>.Wind_Direction Integer default: 0

Wind_Direction = 0 - Front; 1 - Back; 2 - Left; 3 - Right; 4 - Top; 5 - Bottom

See also

Atmospheric Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Volume_Light : Atmospheric

Constructor

volume_light ...

Properties

<Volume_Light>.Fog_Color Color default: (color 255 255 255) -- animatable

<Volume_Light>.attenuation_color Color default: (color 0 0 255) -- animatable

<Volume_Light>.Exponential Integer default: 0

Exponential = 0 - off; 1 - on

<Volume_Light>.Density Float default: 5.0 -- animatable

<Volume_Light>.Max_Light Float default: 90.0 -- animatable

<Volume_Light>.Min_Light Float default: 0.0 -- animatable

<Volume_Light>.Use_Attenuation_Color Integer default: 0

Use_Attenuation_Color = 0 - off; 1 - on

<Volume_Light>.Attenuation_Color_Multiplier Float default: 2.0 -- animatable

<Volume_Light>.Filter_Shadows Integer default: 3

Filter_Shadows = 0 - Low; 1 - Medium; 2 - High; 3 - Use Light Smp Range

<Volume_Light>.Samples Integer default: 20

<Volume_Light>.Auto_Sample Integer default: 1

Auto_Sample = 0 - off; 1 - on

<Volume_Light>.Atten_Start Float default: 100.0 -- animatable

<Volume_Light>.Atten_End Float default: 100.0 -- animatable

<Volume_Light>.Noise_On Integer default: 0

Noise_On = 0 - off; 1 - on

<Volume_Light>.Noise_Amount Float default: 0.0 -- animatable

<Volume_Light>.Link_To_Light Integer default: 0

Link_To_Light = 0 - off; 1 - on

<Volume_Light>.Noise_Type Integer default: 0

Noise_Type = 0 - Regular; 1 - Fractal; 2 - Turbulence

<Volume_Light>.invert Integer default: 0

invert = 0 - off; 1 - on

<Volume_Light>.High_Threshold Float default: 1.0 -- animatable

<Volume_Light>.Low_Threshold Float default: 0.0 -- animatable

<Volume_Light>.Uniformity Float default: 0.0 -- animatable

<Volume_Light>.Levels Float default: 3.0 -- animatable

<Volume_Light>.size Float default: 20.0 -- animatable

<Volume_Light>.phase Float default: 0.0 -- animatable

<Volume_Light>.Wind_Strength Float default: 0.0

<Volume_Light>.Wind_Direction Integer default: 0

Wind_Direction = 0 - Front; 1 - Back; 2 - Left; 3 - Right; 4 - Top; 5 - Bottom

See also

Atmospheric Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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.

lightLevel

Lets you get and set a Float value that defines the global rendering environment (Rendering\Environment) Global Lighting Tint Level.

lightLevelController

Lets you get and set a Controller value that defines the global rendering environment (Rendering\Environment) Global Lighting Tint Level controller.

numAtmospherics

Contains an Integer value that defines the number of atmospheric events, as shown in Rendering\Environment. This variable is read-only.

The following methods set options in the global rendering environment:

getUseEnvironmentMap()

setUseEnvironmentMap <boolean>

Lets you get and set the global rendering environment (Rendering\Environment) Use Map value. If <boolean> is true Use Map is turned on, false it is turned off.

getBackGroundController()

Returns the global rendering environment (Rendering\Environment) background color controller.

setBackGround <time> <point3>

Lets you set a Point3 value that defines the global rendering environment (Rendering\Environment) background color at the specified time. Each component of the Point3 value is in the range of 0 to 255.

setBackGroundController ( <color_controller> | <point3_controller> )

Assigns the specified controller as the global rendering environment (Rendering\Environment) background color controller.

Examples

ambientColor = color 10 10 25

environmentMap = bitmapTexture filename:"foo.bmp"

The following script shows an example of creating Volume Fog and Volume Light atmospherics.

Script:

-- Atmospheric Effects Test Bed

-- create a geosphere, sphere gizmo, onnilight, and targetted camera

geos=geosphere radius:24

sgizmo=spheregizmo radius:40

omni=omnilight farAttenStart:20 farAttenEnd:100 useFarAtten:true v=255

cam=targetcamera pos:[150,-50,100] target:(targetobject())

--

-- put a material on the geosphere

geos.material=standard()

geos.material.selfIllumColor = color 238 241 2

--

-- create a Volume Fog atmospheric. Set name so it has one in Environment dialog.

vf=volume_fog name:"VolFog" soften_gizmo_edges:0.7 exponential:1 density:75

vf.fog_color=color 255 157 0

vf.noise_type=2

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 Render Effect Types.

The properties, operators, and methods that are common to all classes derived directly from the RenderEffect class are described in Render Effects Common Properties, Operators, and Methods.

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 MAXWrapper Common Properties, Operators, and Methods.


Render Effects Common Properties, Operators, and Methods

Render Effects have the following common properties and methods:

Properties

<renderEffect>.name String default: varies

The name as it appears in the Rendering/Effects dialog list. The class name is used as the default name when no name: creation parameter is supplied.

Methods

addEffect <renderEffect>

Adds the render effect to the Rendering/Effects dialog list.

setActive <renderEffect> <boolean>

Sets the render effect active or inactive. If <boolean> is true the render effect is set to active; if false, inactive.

Associated Methods and Global Variables

You can use the following global variables and functions for maintaining the list of render effects in the Rendering/Effects dialog list:

IsActive <renderEffect>

Returns true if the render effect is set to active; false otherwise.

numEffects

Global variable containing an Integer value that defines the number of current render effects defined in the Rendering/Effects dialog list. This variable is read-only.

getEffect <index_integer>

Retrieves the render effect at the indexed position in the Rendering/Effects dialog list. The index is 1-based.

editEffect <renderEffect> [ gizmo: <node> ]

Opens the Rendering/Effects dialog, and opens the rollout for the specified render effect if it has been added to the Render Effects list. If the optional gizmo: argument is specified, and the specified node is a gizmo for the render effect, that gizmo is selected in the render effect's gizmo list.

setEffect <index_integer> <renderEffect>

Sets the render effect at the indexed position in the Rendering/Effects dialog list to the specified render effect. If the Render Effects dialog is displayed when this method is called, the displayed Render Effects list is not updated.

deleteEffect <index_integer>

Deletes the indexed render effect from the Rendering/Effects dialog list. The index is 1-based.

Notes

Unlike most MAXWrapper objects, you can not copy an RenderEffect.

See also

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Render Effect Types

The following list shows the 3ds max Render Effect types:

Blur Effect

Brightness and Contrast

Color Balance Effect

Depth of Field

File Output Effect

Film Grain

Lens Effects


Blur : RenderEffect

Constructor

blur ...

Properties

<blur>.blur_type Integer default: 0 -- animatable

Select a blur type:

0- Uniform

1- Directional

2- Radial

<blur>.bUnifPixRad Float default: 10.0

Determines the intensity of the Blur effect. Increasing the value increases the number of surrounding pixels that each pixel will use to compute its blur. The more pixels used means a greater blur for the image.

<blur>.bUnifAlpha Boolean default: true -- animatable

Applies the Uniform Blur effect to the alpha channel when turned on.

<blur>.bDirUPixRad Float default: 10.0

Determines the horizontal intensity of the Blur effect. Increasing the value increases the number of surrounding pixels that each pixel will use to compute its blur. The more pixels used means a greater horizontal blur for the image.

<blur>.bDirVPixRad Float default: 10.0

Determines the vertical intensity of the Blur effect. Increasing the value increases the number of surrounding pixels that each pixel will use to compute its blur. The more pixels used means a greater vertical blur for the image.

<blur>.bDirUTrail Float default: 0.0

Adds "direction" to your blur by weighting more blur to either side of the U axis. This adds a streaking effect and creates the illusion that your objects or your camera are rapidly moving in a particular direction.

<blur>.bDirVTrail Float default: 0.0

Adds "direction" to your blur by weighting more blur to either side of the V axis. This adds a streaking effect and creates the illusion that your objects or your camera are rapidly moving in a particular direction.

<blur>.bDirRotation Integer default: 0

Rotates the axis of the U and V pixels that will be blurred by the U and V Pixel Radius spinners. By using Rotation with the U and V Pixel Radius spinners you can have the Blur effect applied to any direction in your rendered image. When rotation is 0, U corresponds to the image's X-axis and V corresponds to the image's Y-axis.

<blur>.bDirAlpha Boolean default: true -- animatable

Applies the Directional Blur effect to the Alpha channel when turned on.

<blur>.bRadialPixRad Float default: 20.0

Determines the intensity of the Radius Blur effect. Increasing the value increases the number of surrounding pixels that each pixel will use to compute its blur. The more pixels used means a greater blur for the image.

<blur>.bRadialXOrig Integer default: 320

Sets the origin for the radial blur effect along the X axis.

<blur>.bRadialYOrig Integer default: 240

Sets the origin for the radial blur effect along the Y axis.

axis.<blur>.bRadialTrail Float default: 0.0

Adds "direction" to your blur by weighting more or less blur towards the center of the Blur effect. This adds a streaking effect and creates the illusion that your objects or your camera are rapidly moving in a particular direction.

<blur>.bRadialAlpha Boolean default: true -- animatable

Applies the Radial Blur effect to the Alpha channel when turned on.

<blur>.bRadialNode Node default: undefined

Node to which radial blur is assigned.

<blur>.bRadialUseNode Boolean default: false

Turn on/off use object center for selected node, bradialnode.

<blur>.selImageActive Boolean default: true -- animatable

When on, the blur affects the entire rendered image. This is useful when the blur effect dims your rendered image.

<blur>.selImageBrighten Float default: 0.0

Brightens the entire image.

<blur>.selImageBlend Float default: 100.0

Blends the Blur effect and the Whole Image parameters with the original rendered image. This can be used to create a soft-focus effect.

<blur>.selIBackActive Boolean default: false

Affects everything but the background image or animation when turned on. This is useful when the Blur effect has dimmed you scene objects but not the background.

<blur>.selIBackBrighten Float default: 0.0

Brightens the rendered image except for the background image or animation.

<blur>.selIBackBlend Float default: 100.0

Blends the Blur effect and the Non-Background parameters with the original rendered image.

<blur>.selIBackFRadius Float default: 10.0

Feathers the Blur effect applied to the Non-Background elements of your scene. When using Non-Background as a Pixel Selection you will notice that the scene objects have a hard edge to their blur since the objects are being blurred but the background is not.

<blur>.selLumActive Boolean default: false

Affects any pixels that have luminance values that fall between it's Min and Max values, selLumMin & selLumMax.

<blur>.selLumBrighten Float default: 0.0

Brightens pixels that fall between the Minimum and Maximum luminance values.

<blur>.selLumBlend Float default: 100.0

Blends the Blur effect and the Luminance parameters with the original rendered image.

<blur>.selLumMin Float default: 90.0

The minimum luminance value necessary for each pixel in order for the Blur effect to be applied to the pixel.

<blur>.selLumMax Float default: 100.0

The maximum luminance value a pixel can have in order for the Blur effect to be applied to the pixel.

<blur>.selLumFRadius Float default: 10.0

Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum luminance values. When using Luminance as a Pixel Selection the Blur effect can create a hard edge on the effect.

<blur>.selMaskActive Boolean default: false

When turned on, applies the Blur effect according to the channel selected and mask applied through the Material/Map Browser.

<blur>.selMaskMap TextureMap default: undefined

Map assigned to the blur effect.

<blur>.selMaskChannel Integer default: 4 -- alias: select_mask_channel

Selects a channel that the Blur effect will be applied to:

0- Red

1- Blue

2- Green

3- Alpha

4- Luminance

<blur>.selMaskBrighten Float default: 0.0

Brightens the portions of the image that the Blur effect is applied to.

<blur>.selMaskBlend Float default: 100.0

Blends the Map Mask Blur effect with the original rendered image.

<blur>.selMaskMin Float default: 90.0

The minimum value (RGB, Alpha, or Luminance) a pixel must have in order to have the Blur effect applied to it.

<blur>.selMaskMax Float default: 100.0

The maximum value (RGB, Alpha, or Luminance) a pixel can have for the Blur effect to be applied to it.

<blur>.selMaskFRadius Float default: 10.0

Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum channel values. When using map mask as a Pixel Selection the Blur effect can create a hard edge on the effect.

<blur>.selObjIdsActive Boolean default: false -- animatable

When turned on, applies the Blur effect to an object or part of an object with a specific Object ID, if the object matches the Filter settings.

<blur>.selObjIdsIds Array default: #() -- int array

This array contains all of the Object ID's to which the blur effects will be applied.

<blur>.selObjIdsBrighten Float default: 0.0 -- animatable

Brightens the portion of the image that the Object ID-specific Blur effect is applied to.

<blur>.selObjIdsBlend Float default: 100.0 -- animatable

Blends the Object ID Blur effect with the original rendered image.

<blur>.selObjIdsFRadius Float default: 10.0 -- animatable

Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum luminance values.

<blur>.selObjIdsLumMin Float default: 0.0 -- animatable

The minimum luminance value a pixel must have in order to have the Blur effect applied to it.

<blur>.selObjIdsLumMax Float default: 100.0 -- animatable

The maximum luminance value a pixel can have for the Blur effect to be applied to it.

<blur>.selMatIdsActive Boolean default: false -- animatable

Applies the Blur effect to a material or part of a material with a specific material effects channel, if the material matches the Filter settings.

<blur>.selMatIdsIds Array default: #() -- int array

This array contains all of the Material ID's to which the blur effects will be applied.

<blur>.selMatIdsBrighten Float default: 0.0 -- animatable

Brightens the portion of the image that the Blur effect is applied to.

<blur>.selMatIdsBlend Float default: 100.0 -- animatable

Blends the Material ID Blur effect with the original rendered image.

<blur>.selMatIdsFRadius Float default: 10.0 -- animatable

Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum luminance values.

<blur>.selMatIdsLumMin Float default: 0.0 -- animatable

The minimum luminance value a pixel must have in order to have the Blur effect applied to it.

<blur>.selMatIdsLumMax Float default: 100.0 -- animatable

The maximum luminance value a pixel can have for the Blur effect to be applied to it.

<blur>.selGenBrightType Integer default: 1 -- animatable

Selects the type of brightening applied to the feather falloff curve:

0- Additive

1- Multiplicative

<blur>.select_falloff_curve SubAnim default: SubAnim:Select_Falloff_Curve

<blur.select_falloff_curve>.curve_1 SubAnim default: SubAnim:Curve_1

The brightening curve for the feather falloff.

<blur.select_falloff_curve>.curve_2 SubAnim default: SubAnim:Curve_2

The blend curve for the feather falloff.

See also

Render Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Brightness_and_Contrast : RenderEffect

Constructor

brightness_and_contrast ...

Properties

<Brightness_and_Contrast>.Brightness Float default: 0.5 -- animatable

<Brightness_and_Contrast>.contrast Float default: 0.5 -- animatable

<Brightness_and_Contrast>.ignoreBack Boolean default: false -- animatable, alias: ignore_background

See also

Render Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Color_Balance : RenderEffect

Constructor

color_balance ...

Properties

<Color_Balance>.red Integer default: 0 -- animatable

<Color_Balance>.green Integer default: 0 -- animatable

<Color_Balance>.blue Integer default: 0 -- animatable

<Color_Balance>.preserveLum Boolean default: false -- animatable, alias: Preserve_Luminosity

<Color_Balance>.ignoreBack Boolean default: false -- animatable, alias: Ignore_Background

See also

Render Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Depth_of_Field : RenderEffect

Constructor

depth_of_field ...

Properties

<Depth_of_Field>.AffectAlpha Boolean default: true -- alias: Affect_Alpha

<Depth_of_Field>.camNodeIndex Integer default: -1 -- alias: Camera_Index

camNodeIndex specifies which camera in the Depth of Field camera dropdown is the selected camera. A value of -1 specifies that no camera is selected. The index is otherwise 0-based.

<Depth_of_Field>.focalNodeIndex Integer default: -1 -- alias: Focal_Index

focalNodeIndex specifies which camera in the Depth of Field focal point node dropdown is the selected focal point node. A value of -1 specifies that no focal point node is selected. The index is otherwise 0-based.

<Depth_of_Field>.FocalPoint Integer default: 0 -- alias: Focal_Point

FocalPoint = 0 - Focal Node; 1 - Use Camera

<Depth_of_Field>.FocalType Integer default: 0 -- alias: Focal_Type

FocalType = 0 - Custom; 1 - Use Camera

<Depth_of_Field>.HorizFocalLoss Float default: 10.0 -- animatable, alias: Horiz_Focal_Loss

<Depth_of_Field>.VertFocalLoss Float default: 10.0 -- animatable, alias: Vert_Focal_Loss

<Depth_of_Field>.FocalRange Float default: 100.0 -- animatable, alias: Focal_Range

<Depth_of_Field>.FocalLimit Float default: 200.0 -- animatable, alias: Focal_Limit

Methods

DOF.addCam <Depth_of_Field> <camera_node_name_string>

Adds the specified camera to the Depth of Field camera dropdown. camera_node_name_string is the name of the camera as a string, and must match the case of the camera's name. Returns true if the addition was successful, false if it failed. The normal reason for a failure is that the named camera is not present in the scene.

DOF.addFocalNode <Depth_of_Field> <node_name_string>

Adds the specified node to the Depth of Field focal point node dropdown. node_name_string is the name of the node as a string, and must match the case of the node's name. Returns true if the addition was successful, false if it failed. The normal reason for a failure is that the named node is not present in the scene.

DOF.deleteCam <Depth_of_Field> <index_integer>

Deletes the indexed camera from the Depth of Field camera dropdown, where <index_integer> is the index of the camera in the dropdown. The index is 0-based to maintain consistency with the camNodeIndex property. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the indexed camera is not present in the dropdown.

DOF.deleteCamByName <Depth_of_Field> <camera_node_name_string>

Deletes the specified camera from the Depth of Field camera dropdown. camera_node_name_string is the name of the camera as a string, and must match the case of the camera's name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named camera is not present in the dropdown.

DOF.deleteFocalNode <Depth_of_Field> <index_integer>

Deletes the indexed node from the Depth of Field focal point node dropdown, where <index_integer> is the index of the node in the dropdown. The index is 0-based to maintain consistency with the focalNodeIndex property. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the indexed node is not present in the dropdown.

DOF.deleteFocalNodeByName <Depth_of_Field> <node_name_string>

Deletes the specified node from the Depth of Field focal point node dropdown. node_name_string is the name of the node as a string, and must match the case of the node's name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named node is not present in the dropdown.

See also

Render Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


File_Output : RenderEffect

Constructor

file_output ...

Properties

<File_Output>.bitmap BitMap default: BitMap: -- output bitmap

<File_Output>.channelType Integer default: 0 -- alias: channel_type

channelType = 0 - Whole Image; 1 - Luminance; 2 - Depth; 3 - Alpha

<File_Output>.active Boolean default: true -- animatable

<File_Output>.affectSource Boolean default: false -- animatable, alias: affect_source

<File_Output>.cameraNode Node default: undefined -- alias: camera_node

<File_Output>.nearZ Float default: 0.0 -- animatable, alias: near_z_depth

<File_Output>.farZ Float default: -500.0 -- animatable, alias: far_z_depth

<File_Output>.fitScene Boolean default: true -- animatable, alias: fit_entire_scene

See also

Render Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Film_Grain : RenderEffect

Constructor

film_grain ...

Properties

<Film_Grain>.Grain Float default: 0.2 -- animatable

<Film_Grain>.'Mask Background' Boolean default: false -- animatable; alias: Ignore_Background

See also

Render Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Lens_Effects : RenderEffect

Constructor

lens_effects ...

Properties

<Lens_Effects>.size Float default: 100.0 -- animatable

<Lens_Effects>.intensity Float default: 100.0 -- animatable

<Lens_Effects>.seed Integer default: 1357

<Lens_Effects>.angle Float default: 0.0 -- animatable

<Lens_Effects>.squeeze Float default: 0.0 -- animatable

<Lens_Effects>.affectAlpha Boolean default: true -- alias: Affect_Alpha

<Lens_Effects>.affectZBuffer Boolean default: false -- alias: Affect_Z_Buffer

<Lens_Effects>.distAffectsSize Boolean default: false -- alias: Distance_Affects_Size

<Lens_Effects>.distAffectsIntensity Boolean default: false -- alias: Distance_Affects_Intensity

<Lens_Effects>.centerAffectsSize Boolean default: false -- alias: Off_Center_Affects_Size

<Lens_Effects>.centerAffectsIntensity Boolean default: false -- alias: Off_Center_Affects_Intensity

<Lens_Effects>.innerOcclusionRadius Float default: 3.0 -- animatable, alias: Inner_Occlusion_Radius

<Lens_Effects>.outerOcclusionRadius Float default: 33.0 -- animatable, alias: Outer_Occlusion_Radius

<Lens_Effects>.occlusionAffectsSize Boolean default: true -- alias: Occlusion_Affects_Size

<Lens_Effects>.occlusionAffectsIntensity Boolean default: true -- alias: Occlusion_Affects_Intensity

<Lens_Effects>.affectByAtmosphere Boolean default: false -- alias: Affect_By_Atmosphere

Methods

The following methods add elements to a Lens Effects, load and save a Lens Effects configuration file, add and delete lights, and delete Lens Effects elements.

le.addASec <Lens_Effects>

Adds a Auto Secondary element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.

le.addGlow <Lens_Effects>

Adds a Glow element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.

le.addMSec <Lens_Effects>

Adds a Manual Secondary element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.

le.addRay <Lens_Effects>

Adds a Ray element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.

le.addRing <Lens_Effects>

Adds a Ring element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.

le.addStar <Lens_Effects>

Adds a Star element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.

le.addStreak <Lens_Effects>

Adds a Streak element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.

le.load <Lens_Effects> <filename_string>

le.save <Lens_Effects> <filename_string>

Saves the Lens Effects configuration to the file specified by <filename_string>. Animated parameter values are not saved.

le.numLights <Lens_Effects>

Returns the number of lights in the light list.

le.addLightNode <Lens_Effects> <light_node>

Adds light node to the light list.

le.addLight <Lens_Effects> <light_node_name_string>

Adds the specified light to the Lens Effects Lights dropdown. light_node_name_string is the name of the light as a string, and must match the case of the light's name. Returns true if the addition was successful, false if it failed. The normal reason for a failure is that the named light is not present in the scene.

le.deleteLight <Lens_Effects> <index_integer>

Deletes the indexed light from the Lens Effects Lights dropdown, where <index_integer> is the index of the light in the Lens Effects Lights dropdown. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the indexed light is not present in the dropdown.

le.deleteLightByName <light_node_name_string>

Deletes the named light from the Lens Effects Lights dropdown. light_node_name_string is the name of the light as a string, and must match the case of the light's name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named light is not present in the dropdown.

le.lightIndex <Lens_Effects> <light_node_name_string>

Returns the light list index of the named light. Returns –1 if the light's name is not in the light list.

le.lightName <Lens_Effects> <index>

Returns the node name of the light for the specified light list index. If the index is out of range, a null string will be returned.

le.deleteElement <Lens_Effects> <index_integer>

Deletes the indexed element, where <index_integer> is the index of the element in the Lens Effects composition window. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the indexed element does not exist.

le.deleteElementByName <element_name_string>

Deletes the named element. element_name_string is the name of the element as a string, and must match the case of the element's name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named element does not exist.

See also

Lens_Effects - Auto_Secondary

Lens_Effects - Glow

Lens_Effects - Manual_Secondary

Lens_Effects - Ray

Lens_Effects - Ring

Lens_Effects - Star

Lens_Effects - Streak

Render Effects Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Lens_Effects - Auto_Secondary

Constructor

le.addASec <Lens_Effects>

Properties

<auto_secondary>.elementName String default: "Auto Secondary" -- alias: Name

<auto_secondary>.on Boolean default: true

<auto_secondary>.minSize Float default: 25.0 -- animatable; alias: Min_Size

<auto_secondary>.maxSize Float default: 100.0 -- animatable; alias: Max_Size

<auto_secondary>.axis Float default: 3.0 -- animatable

<auto_secondary>.intensity Float default: 30.0 -- animatable

<auto_secondary>.quantity Integer default: 12 -- animatable

<auto_secondary>.colorSource Float default: 20.0 -- animatable; alias: Source_Color

<auto_secondary>.sides Integer default: 0

sides = 0 - Circular; 1 - Three; 2 - Four; 3 - Five; 4 - Six; 5 - Seven; 6 - Eight

<auto_secondary>.occlusion Float default: 100.0 -- animatable

<auto_secondary>.presets Integer default: 0

presets selects a preset from the indexed list. presets = 0 - no preset.

<auto_secondary>.squeeze Boolean default: false

<auto_secondary>.radialColor1 Color default: (color 0 0 0) -- animatable; alias: Radial_Color_1

<auto_secondary>.radialColor2 Color default: (color 57 34 89) -- animatable; alias: Radial_Color_2

<auto_secondary>.radialColor3 Color default: (color 85 139 85) -- animatable; alias: Radial_Color_3

<auto_secondary>.radialColor4 Color default: (color 190 99 10) -- animatable; alias: Radial_Color_4

<auto_secondary>.colorRadius1 Float default: 90.0 -- animatable; alias: Radius_Color_1

<auto_secondary>.colorRadius2 Float default: 92.0 -- animatable; alias: Radius_Color_2

<auto_secondary>.colorRadius3 Float default: 95.0 -- animatable; alias: Radius_Color_3

<auto_secondary>.colorRadius4 Float default: 98.0 -- animatable; alias: Radius_Color_4

<auto_secondary>.radialMtl TextureMap default: undefined -- alias: Radial_Material

<auto_secondary>.useRadialMtl Boolean default: false -- alias: Apply_Radial_Color_Map

<auto_secondary>.radial_falloff SubAnim

<auto_secondary>.radialMap TextureMap default: undefined -- alias: Radial_Falloff_Map

<auto_secondary>.useRadialMap Boolean default: false -- alias: Apply_Radial_Falloff_Map

<auto_secondary>.circularColorMix Float default: 0.0 -- animatable; alias: Circular_Color_Mix

<auto_secondary>.quadrant1Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_1_Color

<auto_secondary>.quadrant2Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_2_Color

<auto_secondary>.quadrant3Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_3_Color

<auto_secondary>.quadrant4Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_4_Color

<auto_secondary>.circularMtl TextureMap default: undefined -- alias: Circular_Material

<auto_secondary>.useCircularMtl Boolean default: false -- alias: Apply_Circular_Color_Map

<auto_secondary>.circular_falloff SubAnim

<auto_secondary>.circularMap TextureMap default: undefined -- alias: Circular_Falloff_Map

<auto_secondary>.useCircularMap Boolean default: false -- alias: Apply_Circular_Falloff_Map

<auto_secondary>.radial_size SubAnim

<auto_secondary>.radialSizeMap TextureMap default: undefined -- alias: Radial_Size_Map

<auto_secondary>.useRadialSizeMap Boolean default: false -- alias: Apply_Radial_Size_Map

<auto_secondary>.applyLights Boolean default: true -- alias: Apply_to_Lights

<auto_secondary>.applyImage Boolean default: false -- alias: Apply_to_Image

<auto_secondary>.applyImageCenters Boolean default: false -- alias: Apply_to_Image_Centers

<auto_secondary>.sourceObjectID Boolean default: false -- alias: Source_Object_ID

<auto_secondary>.objectID Integer default: 1 -- animatable; alias: Object_ID

<auto_secondary>.sourceEffectsID Boolean default: false -- alias: Source_Effects_ID

<auto_secondary>.effectsID Integer default: 0 -- animatable; alias: Effects_ID

<auto_secondary>.sourceUnclampedColor Boolean default: false -- alias: Source_Unclamped_Color

<auto_secondary>.unclampedColor Float default: 1.0 -- animatable; alias: Unclamped_Color

<auto_secondary>.unclampedColorInvert Boolean default: false -- alias: Source_Unclamped_Color_Invert

<auto_secondary>.sourceSurfaceNormal Boolean default: false -- alias: Source_Surface_Normal

<auto_secondary>.surfaceNormal Float default: 0.0 -- animatable; alias: Surface_Normal

<auto_secondary>.surfaceNormalInvert Boolean default: false -- alias: Source_Surface_Normal_Invert

<auto_secondary>.sourceWhole Boolean default: false -- alias: Source_Whole

<auto_secondary>.sourceAlpha Boolean default: false -- alias: Source_Alpha

<auto_secondary>.alpha Integer default: 0

<auto_secondary>.sourceZBuffer Boolean default: false -- alias: Source_Z_Buffer

<auto_secondary>.zHi Float default: 1000.0 -- animatable; alias: Z_Hi

<auto_secondary>.zLo Float default: 0.0 -- animatable; alias: Z_Lo

<auto_secondary>.filterAll Boolean default: true -- alias: Filter_All

<auto_secondary>.filterEdge Boolean default: false -- alias: Filter_Edge

<auto_secondary>.filterPerimeterAlpha Boolean default: false -- alias: Filter_Perimeter_Alpha

<auto_secondary>.filterPerimeter Boolean default: false -- alias: Filter_Perimeter

<auto_secondary>.filterBrightness Boolean default: false -- alias: Filter_Brightness

<auto_secondary>.brightness Integer default: 0 -- animatable; alias: Bright

<auto_secondary>.brightnessInvert Boolean default: false -- alias: Filter_Brightness_Invert

<auto_secondary>.filterHue Boolean default: false -- alias: Filter_Hue

<auto_secondary>.hueRange Integer default: 0 -- animatable; alias: Hue_Range

<auto_secondary>.hue Color default: (color 255 0 0) -- animatable

<auto_secondary>.applyNoise Boolean default: false -- alias: Apply_Additional_Effects

<auto_secondary>.noiseMap TextureMap default: undefined -- alias: Noise_Map

<auto_secondary>.radial_density SubAnim

<auto_secondary>.radialDensity TextureMap default: undefined -- alias: Radial_Density_Map

<auto_secondary>.useRadialDensity Boolean default: false -- alias: Apply_Radial_Density_Map

<auto_secondary.radial_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<auto_secondary.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<auto_secondary.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<auto_secondary.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

Notes

The le.addASec <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for auto_secondary elements is auto_secondary. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

See also

Lens_Effects : RenderEffect

Value Common Properties, Operators, and Methods


Lens_Effects - Glow

Constructor

le.addGlow <Lens_Effects>

Properties

<glow>.elementName String default: "Glow" -- alias: Name

<glow>.on Boolean default: true

<glow>.size Float default: 30.0 -- animatable

<glow>.intensity Float default: 110.0 -- animatable

<glow>.objectsHide Boolean default: true -- alias: Object_Hide

<glow>.occlusion Float default: 100.0 -- animatable

<glow>.squeeze Boolean default: false

<glow>.useSourceColor Float default: 0.0 -- animatable; alias: Source_Color

<glow>.centerColor Color default: (color 255 255 255) -- animatable; alias: Center_Color

<glow>.edgeColor Color default: (color 255 0 0) -- animatable; alias: Edge_Color

<glow>.radialMtl TextureMap default: undefined -- alias: Radial_Material

<glow>.useRadialMtl Boolean default: false -- alias: Apply_Radial_Color_Map

<glow>.radial_falloff SubAnim

<glow>.radialMap TextureMap default: undefined -- alias: Radial_Falloff_Map

<glow>.useRadialMap Boolean default: false -- alias: Apply_Radial_Falloff_Map

<glow>.circularColorMix Float default: 0.0 -- animatable; alias: Circular_Color_Mix

<glow>.quadrant1Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_1_Color

<glow>.quadrant2Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_2_Color

<glow>.quadrant3Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_3_Color

<glow>.quadrant4Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_4_Color

<glow>.circularMtl TextureMap default: undefined -- alias: Circular_Material

<glow>.useCircularMtl Boolean default: false -- alias: Apply_Circular_Color_Map

<glow>.circular_falloff SubAnim

<glow>.circularMap TextureMap default: undefined -- alias: Circular_Falloff_Map

<glow>.useCircularMap Boolean default: false -- alias: Apply_Circular_Falloff_Map

<glow>.radial_size SubAnim

<glow>.radialSizeMap TextureMap default: undefined -- alias: Radial_Size_Map

<glow>.useRadialSizeMap Boolean default: false -- alias: Apply_Radial_Size_Map

<glow>.applyLights Boolean default: true -- alias: Apply_to_Lights

<glow>.applyImage Boolean default: true -- alias: Apply_to_Image

<glow>.applyImageCenters Boolean default: false -- alias: Apply_to_Image_Centers

<glow>.sourceObjectID Boolean default: false -- alias: Source_Object_ID

<glow>.objectID Integer default: 1 -- animatable; alias: Object_ID

<glow>.sourceEffectsID Boolean default: false -- alias: Source_Effects_ID

<glow>.effectsID Integer default: 1 -- animatable; alias: Effects_ID

<glow>.sourceUnclampedColor Boolean default: false -- alias: Source_Unclamped_Color

<glow>.unclampedColor Float default: 1.0 -- animatable; alias: Unclamped_Color

<glow>.unclampedColorInvert Boolean default: false -- alias: Source_Unclamped_Color_Invert

<glow>.sourceSurfaceNormal Boolean default: false -- alias: Source_Surface_Normal

<glow>.surfaceNormal Float default: 0.0 -- animatable; alias: Surface_Normal

<glow>.surfaceNormalInvert Boolean default: false -- alias: Source_Surface_Normal_Invert

<glow>.sourceWhole Boolean default: false -- alias: Source_Whole

<glow>.sourceAlpha Boolean default: false -- alias: Source_Alpha

<glow>.alpha Integer default: 0 -- animatable

<glow>.sourceZBuffer Boolean default: false -- alias: Source_Z_Buffer

<glow>.zHi Float default: 1000.0 -- animatable; alias: Z_Hi

<glow>.zLo Float default: 0.0 -- animatable; alias: Z_Lo

<glow>.filterAll Boolean default: true -- alias: Filter_All

<glow>.filterEdge Boolean default: false -- alias: Filter_Edge

<glow>.filterPerimeterAlpha Boolean default: false -- alias: Filter_Perimeter_Alpha

<glow>.filterPerimeter Boolean default: false -- alias: Filter_Perimeter

<glow>.filterBrightness Boolean default: false -- alias: Filter_Brightness

<glow>.brightness Integer default: 0 -- animatable; alias: Bright

<glow>.brightnessInvert Boolean default: false -- alias: Filter_Brightness_Invert

<glow>.filterHue Boolean default: false -- alias: Filter_Hue

<glow>.hueRange Integer default: 0 -- animatable; alias: Hue_Range

<glow>.hue Color default: (color 255 0 0) -- animatable

<glow>.applyNoise Boolean default: false -- alias: Apply_Additional_Effects

<glow>.noiseMap TextureMap default: undefined -- alias: Noise_Map

<glow>.radial_density SubAnim

<glow>.radialDensity TextureMap default: undefined -- alias: Radial_Density_Map

<glow>.useRadialDensity Boolean default: false -- alias: Apply_Radial_Density_Map

<glow.radial_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<glow.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<glow.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<glow.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

Notes

The le.addGlow <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for glow elements is glow. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

See also

Lens_Effects : RenderEffect

Value Common Properties, Operators, and Methods


Lens_Effects - Manual_Secondary

Constructor

le.addMSec <Lens_Effects>

Properties

<manual_secondary>.elementName String default: "Manual Secondary" -- alias: Name

<manual_secondary>.on Boolean default: true

<manual_secondary>.size Float default: 50.0 -- animatable

<manual_secondary>.intensity Float default: 30.0 -- animatable

<manual_secondary>.plane Float default: 150.0 -- animatable

<manual_secondary>.colorSource Float default: 20.0 -- animatable; alias: Source_Color

<manual_secondary>.sides Integer default: 0

sides = 0 - Circular; 1 - Three; 2 - Four; 3 - Five; 4 - Six; 5 - Seven; 6 - Eight

<manual_secondary>.occlusion Float default: 100.0 -- animatable

<manual_secondary>.squeeze Boolean default: false

<manual_secondary>.presets Integer default: 0

presets selects a preset from the indexed list. presets = 0 - no preset.

<manual_secondary>.radialColor1 Color default: (color 0 0 0) -- animatable; alias: Radial_Color_1

<manual_secondary>.radialColor2 Color default: (color 57 34 89) -- animatable; alias: Radial_Color_2

<manual_secondary>.radialColor3 Color default: (color 85 139 85) -- animatable; alias: Radial_Color_3

<manual_secondary>.radialColor4 Color default: (color 190 99 10) -- animatable; alias: Radial_Color_4

<manual_secondary>.colorRadius1 Float default: 90.0 -- animatable; alias: Radius_Color_1

<manual_secondary>.colorRadius2 Float default: 92.0 -- animatable; alias: Radius_Color_2

<manual_secondary>.colorRadius3 Float default: 95.0 -- animatable; alias: Radius_Color_3

<manual_secondary>.colorRadius4 Float default: 98.0 -- animatable; alias: Radius_Color_4

<manual_secondary>.radialMtl TextureMap default: undefined -- alias: Radial_Material

<manual_secondary>.useRadialMtl Boolean default: false -- alias: Apply_Radial_Color_Map

<manual_secondary>.radial_falloff SubAnim

<manual_secondary>.radialMap TextureMap default: undefined -- alias: Radial_Falloff_Map

<manual_secondary>.useRadialMap Boolean default: false -- alias: Apply_Radial_Falloff_Map

<manual_secondary>.circularColorMix Float default: 0.0 -- animatable; alias: Circular_Color_Mix

<manual_secondary>.quadrant1Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_1_Color

<manual_secondary>.quadrant2Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_2_Color

<manual_secondary>.quadrant3Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_3_Color

<manual_secondary>.quadrant4Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_4_Color

<manual_secondary>.circularMtl TextureMap default: undefined -- alias: Circular_Material

<manual_secondary>.useCircularMtl Boolean default: false -- alias: Apply_Circular_Color_Map

<manual_secondary>.circular_falloff SubAnim

<manual_secondary>.circularMap TextureMap default: undefined -- alias: Circular_Falloff_Map

<manual_secondary>.useCircularMap Boolean default: false -- alias: Apply_Circular_Falloff_Map

<manual_secondary>.radial_size SubAnim

<manual_secondary>.radialSizeMap TextureMap default: undefined -- alias: Radial_Size_Map

<manual_secondary>.useRadialSizeMap Boolean default: false -- alias: Apply_Radial_Size_Map

<manual_secondary>.applyLights Boolean default: true -- alias: Apply_to_Lights

<manual_secondary>.applyImage Boolean default: false -- alias: Apply_to_Image

<manual_secondary>.applyImageCenters Boolean default: false -- alias: Apply_to_Image_Centers

<manual_secondary>.sourceObjectID Boolean default: false -- alias: Source_Object_ID

<manual_secondary>.objectID Integer default: 1 -- animatable; alias: Object_ID

<manual_secondary>.sourceEffectsID Boolean default: false -- alias: Source_Effects_ID

<manual_secondary>.effectsID Integer default: 0 -- animatable; alias: Effects_ID

<manual_secondary>.sourceUnclampedColor Boolean default: false -- alias: Source_Unclamped_Color

<manual_secondary>.unclampedColor Float default: 1.0 -- animatable; alias: Unclamped_Color

<manual_secondary>.unclampedColorInvert Boolean default: false -- alias: Source_Unclamped_Color_Invert

<manual_secondary>.sourceSurfaceNormal Boolean default: false -- alias: Source_Surface_Normal

<manual_secondary>.surfaceNormal Float default: 0.0 -- animatable; alias: Surface_Normal

<manual_secondary>.surfaceNormalInvert Boolean default: false -- alias: Source_Surface_Normal_Invert

<manual_secondary>.sourceWhole Boolean default: false -- alias: Source_Whole

<manual_secondary>.sourceAlpha Boolean default: false -- alias: Source_Alpha

<manual_secondary>.alpha Integer default: 0

<manual_secondary>.sourceZBuffer Boolean default: false -- alias: Source_Z_Buffer

<manual_secondary>.zHi Float default: 1000.0 -- animatable; alias: Z_Hi

<manual_secondary>.zLo Float default: 0.0 -- animatable; alias: Z_Lo

<manual_secondary>.filterAll Boolean default: true -- alias: Filter_All

<manual_secondary>.filterEdge Boolean default: false -- alias: Filter_Edge

<manual_secondary>.filterPerimeterAlpha Boolean default: false -- alias: Filter_Perimeter_Alpha

<manual_secondary>.filterPerimeter Boolean default: false -- alias: Filter_Perimeter

<manual_secondary>.filterBrightness Boolean default: false -- alias: Filter_Brightness

<manual_secondary>.brightness Integer default: 0 -- animatable; alias: Bright

<manual_secondary>.brightnessInvert Boolean default: false -- alias: Filter_Brightness_Invert

<manual_secondary>.filterHue Boolean default: false -- alias: Filter_Hue

<manual_secondary>.hueRange Integer default: 0 -- animatable; alias: Hue_Range

<manual_secondary>.hue Color default: (color 255 0 0) -- animatable

<manual_secondary>.applyNoise Boolean default: false -- alias: Apply_Additional_Effects

<manual_secondary>.noiseMap TextureMap default: undefined -- alias: Noise_Map

<manual_secondary>.radial_density SubAnim

<manual_secondary>.radialDensity TextureMap default: undefined -- alias: Radial_Density_Map

<manual_secondary>.useRadialDensity Boolean default: false -- alias: Apply_Radial_Density_Map

<manual_secondary.radial_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<manual_secondary.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<manual_secondary.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<manual_secondary.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

Notes

The le.addMSec <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for manual_secondary elements is manual_secondary. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

See also

Lens_Effects : RenderEffect

Value Common Properties, Operators, and Methods


Lens_Effects - Ray

Constructor

le.addRay <Lens_Effects>

Properties

<ray>.elementName String default: "Ray" -- alias: Name

<ray>.on Boolean default: true

<ray>.size Float default: 300.0 -- animatable

<ray>.intensity Float default: 10.0 -- animatable

<ray>.number Integer default: 100 -- animatable; alias: Quantity

<ray>.angle Float default: 0.0 -- animatable

<ray>.sharpness Float default: 8.0 -- animatable

<ray>.objectsHide Boolean default: false

<ray>.occlusion Float default: 100.0 -- animatable

<ray>.squeeze Boolean default: false

<ray>.colorSource Float default: 100.0 -- animatable; alias: Source_Color

<ray>.centerColor Color default: (color 255 255 255) -- animatable; alias: Center_Color

<ray>.edgeColor Color default: (color 255 0 0) -- animatable; alias: Edge_Color

<ray>.radialMtl TextureMap default: undefined -- alias: Radial_Material

<ray>.useRadialMtl Boolean default: false -- alias: Apply_Radial_Color_Map

<ray>.radial_falloff SubAnim

<ray>.radialMap TextureMap default: undefined -- alias: Radial_Falloff_Map

<ray>.useRadialMap Boolean default: false -- alias: Apply_Radial_Falloff_Map

<ray>.circularColorMix Float default: 0.0 -- animatable; alias: Circular_Color_Mix

<ray>.quadrant1Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_1_Color

<ray>.quadrant2Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_2_Color

<ray>.quadrant3Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_3_Color

<ray>.quadrant4Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_4_Color

<ray>.circularMtl TextureMap default: undefined

Circular_Material

<ray>.useCircularMtl Boolean default: false -- alias: Apply_Circular_Color_Map

<ray>.circular_falloff SubAnim

<ray>.circularMap TextureMap default: undefined -- alias: Circular_Falloff_Map

<ray>.useCircularMap Boolean default: false -- alias: Apply_Circular_Falloff_Map

<ray>.radial_size SubAnim

<ray>.radialSizeMap TextureMap default: undefined -- alias: Radial_Size_Map

<ray>.useRadialSizeMap Boolean default: false -- alias: Apply_Radial_Size_Map

<ray>.applyLights Boolean default: true -- alias: Apply_to_Lights

<ray>.applyImage Boolean default: true -- alias: Apply_to_Image

<ray>.applyImageCenters Boolean default: false -- alias: Apply_to_Image_Centers

<ray>.sourceObjectID Boolean default: false -- alias: Source_Object_ID

<ray>.objectID Integer default: 1 -- animatable; alias: Object_ID

<ray>.sourceEffectsID Boolean default: false -- alias: Source_Effects_ID

<ray>.effectsID Integer default: 1 -- animatable; alias: Effects_ID

<ray>.sourceUnclampedColor Boolean default: false -- alias: Source_Unclamped_Color

<ray>.unclampedColor Float default: 1.0 -- animatable; alias: Unclamped_Color

<ray>.unclampedColorInvert Boolean default: false -- alias: Source_Unclamped_Color_Invert

<ray>.sourceSurfaceNormal Boolean default: false -- alias: Source_Surface_Normal

<ray>.surfaceNormal Float default: 0.0 -- animatable; alias: Surface_Normal

<ray>.surfaceNormalInvert Boolean default: false -- alias: Source_Surface_Normal_Invert

<ray>.sourceWhole Boolean default: false -- alias: Source_Whole

<ray>.sourceAlpha Boolean default: false -- alias: Source_Alpha

<ray>.alpha Integer default: 0 -- animatable

<ray>.sourceZBuffer Boolean default: false -- alias: Source_Z_Buffer

<ray>.zHi Float default: 1000.0 -- animatable; alias: Z_Hi

<ray>.zLo Float default: 0.0 -- animatable; alias: Z_Lo

<ray>.filterAll Boolean default: true -- alias: Filter_All

<ray>.filterEdge Boolean default: false -- alias: Filter_Edge

<ray>.filterPerimeterAlpha Boolean default: false -- alias: Filter_Perimeter_Alpha

<ray>.filterPerimeter Boolean default: false -- alias: Filter_Perimeter

<ray>.filterBrightness Boolean default: false -- alias: Filter_Brightness

<ray>.brightness Integer default: 0 -- animatable; alias: Bright

<ray>.brightnessInvert Boolean default: false -- alias: Filter_Brightness_Invert

<ray>.filterHue Boolean default: false -- alias: Filter_Hue

<ray>.hueRange Integer default: 0 -- animatable; alias: Hue_Range

<ray>.hue Color default: (color 255 0 0) -- animatable

<ray>.applyNoise Boolean default: false -- alias: Apply_Additional_Effects

<ray>.noiseMap TextureMap default: undefined -- alias: Noise_Map

<ray>.radial_density SubAnim

<ray>.radialDensity TextureMap default: undefined -- alias: Radial_Density_Map

<ray>.useRadialDensity Boolean default: false -- alias: Apply_Radial_Density_Map

<ray.radial_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<ray.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<ray.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<ray.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

Notes

The le.addRay <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for ray elements is ray. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

See also

Lens_Effects : RenderEffect

Value Common Properties, Operators, and Methods


Lens_Effects - Ring

Constructor

le.addRing <Lens_Effects>

Properties

<ring>.elementName String default: "Ring" -- alias: Name

<ring>.on Boolean default: true

<ring>.size Float default: 75.0 -- animatable

<ring>.intensity Float default: 75.0 -- animatable

<ring>.plane Float default: 0.0 -- animatable

<ring>.thickness Float default: 10.0 -- animatable

<ring>.objectsHide Boolean default: false -- alias: Object_Hide

<ring>.occlusion Float default: 100.0 -- animatable

<ring>.squeeze Boolean default: false

<ring>.colorSource Float default: 0.0 -- animatable; alias: Source_Color

<ring>.centerColor Color default: (color 255 255 255) -- animatable; alias: Center_Color

<ring>.edgeColor Color default: (color 255 0 0) -- animatable; alias: Edge_Color

<ring>.radialMtl TextureMap default: undefined -- alias: Radial_Material

<ring>.useRadialMtl Boolean default: false -- alias: Apply_Radial_Color_Map

<ring>.radial_falloff SubAnim

<ring>.radialMap TextureMap default: undefined -- alias: Radial_Falloff_Map

<ring>.useRadialMap Boolean default: false -- alias: Apply_Radial_Falloff_Map

<ring>.circularColorMix Float default: 0.0 -- animatable; alias: Circular_Color_Mix

<ring>.quadrant1Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_1_Color

<ring>.quadrant2Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_2_Color

<ring>.quadrant3Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_3_Color

<ring>.quadrant4Color Color default: (color 255 0 0) -- animatable; alias: Quadrant_4_Color

<ring>.circularMtl TextureMap default: undefined -- alias: Circular_Material

<ring>.useCircularMtl Boolean default: false -- alias: Apply_Circular_Color_Map

<ring>.circular_falloff SubAnim

<ring>.circularMap TextureMap default: undefined -- alias: Circular_Falloff_Map

<ring>.useCircularMap Boolean default: false -- alias: Apply_Circular_Falloff_Map

<ring>.radial_size SubAnim

<ring>.radialSizeMap TextureMap default: undefined -- alias: Radial_Size_Map

<ring>.useRadialSizeMap Boolean default: false -- alias: Apply_Radial_Size_Map

<ring>.applyLights Boolean default: true -- alias: Apply_to_Lights

<ring>.applyImage Boolean default: true -- alias: Apply_to_Image

<ring>.applyImageCenters Boolean default: false -- alias: Apply_to_Image_Centers

<ring>.sourceObjectID Boolean default: false -- alias: Source_Object_ID

<ring>.objectID Integer default: 1 -- animatable; alias: Object_ID

<ring>.sourceEffectsID Boolean default: false -- alias: Source_Effects_ID

<ring>.effectsID Integer default: 1 -- animatable; alias: Effects_ID

<ring>.sourceUnclampedColor Boolean default: false -- alias: Source_Unclamped_Color

<ring>.unclampedColor Float default: 1.0 -- animatable; alias: Unclamped_Color

<ring>.unclampedColorInvert Boolean default: false -- alias: Source_Unclamped_Color_Invert

<ring>.sourceSurfaceNormal Boolean default: false -- alias: Source_Surface_Normal

<ring>.surfaceNormal Float default: 0.0 -- animatable; alias: Surface_Normal

<ring>.surfaceNormalInvert Boolean default: false -- alias: Source_Surface_Normal_Invert

<ring>.sourceWhole Boolean default: false -- alias: Source_Whole

<ring>.sourceAlpha Boolean default: false -- alias: Source_Alpha

<ring>.alpha Integer default: 0 -- animatable

<ring>.sourceZBuffer Boolean default: false -- alias: Source_Z_Buffer

<ring>.zHi Float default: 1000.0 -- animatable; alias: Z_Hi

<ring>.zLo Float default: 0.0 -- animatable; alias: Z_Lo

<ring>.filterAll Boolean default: true -- alias: Filter_All

<ring>.filterEdge Boolean default: false -- alias: Filter_Edge

<ring>.filterPerimeterAlpha Boolean default: false -- alias: Filter_Perimeter_Alpha

<ring>.filterPerimeter Boolean default: false -- alias: Filter_Perimeter

<ring>.filterBrightness Boolean default: false -- alias: Filter_Brightness

<ring>.brightness Integer default: 0 -- animatable; alias: Bright

<ring>.brightnessInvert Boolean default: false -- alias: Filter_Brightness_Invert

<ring>.filterHue Boolean default: false -- alias: Filter_Hue

<ring>.hueRange Integer default: 0 -- animatable; alias: Hue_Range

<ring>.hue Color default: (color 255 0 0) -- animatable

<ring>.applyNoise Boolean default: false -- alias: Apply_Additional_Effects

<ring>.noiseMap TextureMap default: undefined -- alias: Noise_Map

<ring>.radial_density SubAnim

<ring>.radialDensity TextureMap default: undefined -- alias: Radial_Density_Map

<ring>.useRadialDensity Boolean default: false -- alias: Apply_Radial_Density_Map

<ring.radial_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<ring.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<ring.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<ring.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

Notes

The le.addRing <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for ring elements is ring. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

See also

Lens_Effects : RenderEffect

Value Common Properties, Operators, and Methods


Lens_Effects - Star

Constructor

le.addStar <Lens_Effects>

Properties

<star>.elementName String default: "Star" -- alias: Name

<star>.on Boolean default: true

<star>.size Float default: 200.0 -- animatable

<star>.intensity Float default: 20.0 -- animatable

<star>.width Float default: 8.0 -- animatable

<star>.angle Float default: 0.0 -- animatable

<star>.taper Float default: 0.5 -- animatable

<star>.sharp Float default: 9.5 -- animatable; alias: Sharpness

<star>.quantity Integer default: 6 -- animatable

<star>.objectsHide Boolean default: false -- alias: Object_Hide

<star>.occlusion Float default: 50.0 -- animatable

<star>.squeeze Boolean default: false

<star>.colorSource Float default: 100.0 -- animatable; alias: Source_Color

<star>.centerColor Color default: (color 0 0 255) -- animatable; alias: Center_Color

<star>.edgeColor Color default: (color 255 255 255) -- animatable; alias: Edge_Color

<star>.radialMtl TextureMap default: undefined -- alias: Radial_Material

<star>.useRadialMtl Boolean default: false -- alias: Apply_Radial_Color_Map

<star>.radial_falloff SubAnim

<star>.radialMap TextureMap default: undefined -- alias: Radial_Falloff_Map

<star>.useRadialMap Boolean default: false -- alias: Apply_Radial_Falloff_Map

<star>.circularColorMix Float default: 0.0 -- animatable; alias: Circular_Color_Mix

<star>.leftSectionColor Color default: (color 0 0 255) -- animatable; alias: Left_Section_Color

<star>.centerSectionColor Color default: (color 255 255 255) -- animatable; alias: Center_Section_Color

<star>.rightSectionColor Color default: (color 0 0 255) -- animatable; alias: Right_Section_Color

<star>.circularMtl TextureMap default: undefined -- alias: Circular_Material

<star>.useCircularMtl Boolean default: false -- alias: Apply_Circular_Color_Map

<star>.circular_falloff SubAnim

<star>.circularMap TextureMap default: undefined -- alias: Circular_Falloff_Map

<star>.useCircularMap Boolean default: false -- alias: Apply_Circular_Falloff_Map

<star>.radial_size SubAnim

<star>.radialSizeMap TextureMap default: undefined -- alias: Radial_Size_Map

<star>.useRadialSizeMap Boolean default: false -- alias: Apply_Radial_Size_Map

<star>.applyLights Boolean default: true -- alias: Apply_to_Lights

<star>.applyImage Boolean default: true -- alias: Apply_to_Image

<star>.applyImageCenters Boolean default: false -- alias: Apply_to_Image_Centers

<star>.sourceObjectID Boolean default: false -- alias: Source_Object_ID

<star>.objectID Integer default: 1 -- animatable; alias: Object_ID

<star>.sourceEffectsID Boolean default: false -- alias: Source_Effects_ID

<star>.effectsID Integer default: 1 -- animatable; alias: Effects_ID

<star>.sourceUnclampedColor Boolean default: false -- alias: Source_Unclamped_Color

<star>.unclampedColor Float default: 1.0 -- animatable; alias: Unclamped_Color

<star>.unclampedColorInvert Boolean default: false -- alias: Source_Unclamped_Color_Invert

<star>.sourceSurfaceNormal Boolean default: false -- alias: Source_Surface_Normal

<star>.surfaceNormal Float default: 0.0 -- animatable; alias: Surface_Normal

<star>.surfaceNormalInvert Boolean default: false -- alias: Source_Surface_Normal_Invert

<star>.sourceWhole Boolean default: false -- alias: Source_Whole

<star>.sourceAlpha Boolean default: false -- alias: Source_Alpha

<star>.alpha Integer default: 0 -- animatable

<star>.sourceZBuffer Boolean default: false -- alias: Source_Z_Buffer

<star>.zHi Float default: 1000.0 -- animatable; alias: Z_Hi

<star>.zLo Float default: 0.0 -- animatable; alias: Z_Lo

<star>.filterAll Boolean default: true -- alias: Filter_All

<star>.filterEdge Boolean default: false -- alias: Filter_Edge

<star>.filterPerimeterAlpha Boolean default: false -- alias: Filter_Perimeter_Alpha

<star>.filterPerimeter Boolean default: false -- alias: Filter_Perimeter

<star>.filterBrightness Boolean default: false -- alias: Filter_Brightness

<star>.brightness Integer default: 0 -- animatable; alias: Bright

<star>.brightnessInvert Boolean default: false -- alias: Filter_Brightness_Invert

<star>.filterHue Boolean default: false -- alias: Filter_Hue

<star>.hueRange Integer default: 0 -- animatable; alias: Hue_Range

<star>.hue Color default: (color 255 0 0) -- animatable

<star>.applyNoise Boolean default: false -- alias: Apply_Additional_Effects

<star>.noiseMap TextureMap default: undefined -- alias: Noise_Map

<star>.radial_density SubAnim

<star>.radialDensity TextureMap default: undefined -- alias: Radial_Density_Map

<star>.useRadialDensity Boolean default: false -- alias: Apply_Radial_Density_Map

<star.radial_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<star.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<star.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<star.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

Notes

The le.addStar <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for star elements is star. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

See also

Lens_Effects : RenderEffect

Value Common Properties, Operators, and Methods


Lens_Effects - Streak

Constructor

le.addStreak <Lens_Effects>

Properties

<streak>.elementName String default: "Streak" -- alias: Name

<streak>.on Boolean default: true

<streak>.size Float default: 50.0 -- animatable

<streak>.intensity Float default: 30.0 -- animatable

<streak>.width Float default: 2.0 -- animatable

<streak>.angle Float default: 0.0 -- animatable

<streak>.taper Float default: 0.5 -- animatable

<streak>.sharp Float default: 9.8 -- animatable; alias: Sharpness

<streak>.objectsHide Boolean default: false -- alias: Object_Hide

<streak>.occlusion Float default: 100.0 -- animatable

<streak>.squeeze Boolean default: false

<streak>.colorSource Float default: 100.0 -- animatable; alias: Source_Color

<streak>.centerColor Color default: (color 0 0 255) -- animatable; alias: Center_Color

<streak>.edgeColor Color default: (color 255 255 255) -- animatable; alias: Edge_Color

<streak>.radialMtl TextureMap default: undefined -- alias: Radial_Material

<streak>.useRadialMtl Boolean default: false -- alias: Apply_Radial_Color_Map

<streak>.radial_falloff SubAnim

<streak>.radialMap TextureMap default: undefined -- alias: Radial_Falloff_Map

<streak>.useRadialMap Boolean default: false -- alias: Apply_Radial_Falloff_Map

<streak>.circularColorMix Float default: 50.0 -- animatable; alias: Circular_Color_Mix

<streak>.quadrant1Color Color default: (color 0 0 0) -- animatable; alias: Left_Section_Color

<streak>.quadrant2Color Color default: (color 255 255 255) -- animatable; alias: Center_Section_Color

<streak>.quadrant3Color Color default: (color 0 0 0) -- animatable; alias: Right_Section_Color

<streak>.circularMtl TextureMap default: undefined -- alias: Circular_Material

<streak>.useCircularMtl Boolean default: false -- alias: Apply_Circular_Color_Map

<streak>.circular_falloff SubAnim

<streak>.circularMap TextureMap default: undefined -- alias: Circular_Falloff_Map

<streak>.useCircularMap Boolean default: false -- alias: Apply_Circular_Falloff_Map

<streak>.radial_size SubAnim

<streak>.radialSizeMap TextureMap default: undefined -- alias: Radial_Size_Map

<streak>.useRadialSizeMap Boolean default: false -- alias: Apply_Radial_Size_Map

<streak>.applyLights Boolean default: true -- alias: Apply_to_Lights

<streak>.applyImage Boolean default: true -- alias: Apply_to_Image

<streak>.applyImageCenters Boolean default: false -- alias: Apply_to_Image_Centers

<streak>.sourceObjectID Boolean default: false -- alias: Source_Object_ID

<streak>.objectID Integer default: 1 -- animatable; alias: Object_ID

<streak>.sourceEffectsID Boolean default: false -- alias: Source_Effects_ID

<streak>.effectsID Integer default: 1 -- animatable; alias: Effects_ID

<streak>.sourceUnclampedColor Boolean default: false -- alias: Source_Unclamped_Color

<streak>.unclampedColor Float default: 1.0 -- animatable; alias: Unclamped_Color

<streak>.unclampedColorInvert Boolean default: false -- alias: Source_Unclamped_Color_Invert

<streak>.sourceSurfaceNormal Boolean default: false -- alias: Source_Surface_Normal

<streak>.surfaceNormal Float default: 0.0 -- animatable; alias: Surface_Normal

<streak>.surfaceNormalInvert Boolean default: false -- alias: Source_Surface_Normal_Invert

<streak>.sourceWhole Boolean default: false -- alias: Source_Whole

<streak>.sourceAlpha Boolean default: false -- alias: Source_Alpha

<streak>.alpha Integer default: 0 -- animatable

<streak>.sourceZBuffer Boolean default: false -- alias: Source_Z_Buffer

<streak>.zHi Float default: 1000.0 -- animatable; alias: Z_Hi

<streak>.zLo Float default: 0.0 -- animatable; alias: Z_Lo

<streak>.filterAll Boolean default: true -- alias: Filter_All

<streak>.filterEdge Boolean default: false -- alias: Filter_Edge

<streak>.filterPerimeterAlpha Boolean default: false -- alias: Filter_Perimeter_Alpha

<streak>.filterPerimeter Boolean default: false -- alias: Filter_Perimeter

<streak>.filterBrightness Boolean default: false -- alias: Filter_Brightness

<streak>.brightness Integer default: 0 -- animatable; alias: Bright

<streak>.brightnessInvert Boolean default: false -- alias: Filter_Brightness_Invert

<streak>.filterHue Boolean default: false -- alias: Filter_Hue

<streak>.hueRange Integer default: 0 -- animatable; alias: Hue_Range

<streak>.hue Color default: (color 255 0 0) -- animatable

<streak>.applyNoise Boolean default: false -- alias: Apply_Additional_Effects

<streak>.noiseMap TextureMap default: undefined -- alias: Noise_Map

<streak>.radial_density SubAnim

<streak>.radialDensity TextureMap default: undefined -- alias: Radial_Density_Map

<streak>.useRadialDensity Boolean default: false -- alias: Apply_Radial_Density_Map

<streak.radial_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<streak.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<streak.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

<streak.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

Notes

The le.addStreak <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for streak elements is streak. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

See also

Lens_Effects : RenderEffect

Value Common Properties, Operators, and Methods


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 Track View.

MAXTVNode : Value is the class whose instances represent track view global track nodes. Each MAXTVNode can contain any number of MAXTVNodes or animation controllers. The MAXTVNodes and controllers within a MAXTVNode are shown as properties of the MAXTVNode so you navigate through the nesting using property access. A MAXTVNode itself does not store animation data, but rather acts as a container that can store one or more MAXTVNode or animation controller.

There are three track view nodes you can access through global variables: the root node to which you can add new custom tracks; the existing Global Tracks node which provides access to the global track controllers; and the Video Post tracks node which provides access to any video post controllers. These nodes are also accessible as properties on the root node.

Constructor

trackViewNodes

Global variable containing the top-level World, or root, node in Track View. This variable is read-only.

globalTracks

Global variable containing the top-level Global Tracks node in Track View. This variable is read-only.

videoPostTracks

Global variable containing the top-level Video Post Track View node. This variable is read-only. This variable contains the value undefined in 3D Studio VIZ.

newTrackViewNode [ <maxtvnode> ] <name_string> [ #hidden ]

if the <maxtvnode> argument is supplied, adds a sub-track node to it. If not, creates a new 'top-level' track in the Track View. If the optional #hidden flag is supplied, the node is not visible in the Track View.

Properties

<maxtvnode>.name String

the track view node name as it appears in Track View

The sub-tracks and sub-controllers for a track view node are also shown as properties of the track view node. For example, the additional default properties for global trackViewNodes are:

TrackViewNodes.Global_Tracks MAXTVNode

TrackViewNodes.Video_Post MAXTVNode

And the additional default properties for global globalTracks are:

GlobalTracks.float float_list controller

GlobalTracks.point3 point3_list controller

GlobalTracks.position position_list controller

GlobalTracks.rotation rotation_list controller

GlobalTracks.scale scale_list controller

GlobalTracks.Block_Control block_control controller

Methods

deleteTrackViewNode [ <parent_maxtvnode> ] <maxtvnode>

deletes the given node from the supplied parent, or the top-level if the parent is not specified

addTrackViewController <maxtvnode> <controller> <name>

adds the sub-controller to the given Track View node. The

deleteTrackViewController <maxtvnode> <controller>

deletes the controller from the given Track View node

Examples:

-- access a video post track

videoPostTracks.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()

See also

Value Common Properties, Operators, and Methods


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

Overview of the Principal NURBS Classes

Using the NURBS Classes and Functions to Create and Modify 3ds max NURBS Models

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 NURBS Classes. 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.

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 is the main base class, with NURBSPoint, NURBSControlVertex, NURBSCurve, NURBSSurface, NURBSCVCurve, and NURBSPointCurve 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, NURBSSelection, NURBSSet, NURBSSurfaceApproximation, and NURBSTextureSurface 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.

The NURBSSet class is the class used when developers want to create 3ds max NURBS objects, or retrieve data from existing 3ds max NURBS objects. The NURBSSet acts as a container for the other objects. This class contains a table of the various NURBSObject derived entities (points, curves, surfaces) used to make up the set. Additionally it has two 'fuse' tables: one for fuse curves and one for fuse surfaces. These are used to allow the CVs in the curves or surfaces to be 'stitched' or 'fused' together so that if one curve or surface moves the other moves with it. This class also has the surface-approximation properties that control the object's tessellation into triangle meshes for use in the viewports and the production renderer.

The NURBSPoint classes describe a point in 3D space. Depending on the specific class, points can be either independent or dependent. Independent points are those that don't rely on other objects to define their location. Dependent points are related to the objects they depend on such that the relationship established initially remains if the point, curve or surface moves. For example, a point can be created such that it always remains a certain distance from another point. The options are XYZ-relative, along a normal, or along a tangent (or set of tangents for a surface-dependent constrained point).

The NURBSControlVertex class defines a Control Vertex of a NURBS Curve or NURBS Surface. This class shares may of the same properties as a NURBSPoint and has the added property of a rational weight. The weight value of a CV is rational. That is, it is relative to other CVs in the curve or surface. Changing the weight of all CVs at once has no effect, because this doesn't change the ratio between weights.

The NURBSCurve classes describe the properties of NURBS curves. As with the NURBSPoint classes, depending on the specific class, curves can be either independent or dependent. Independent curves are those that don't rely on other objects to define their location. A dependent curve is an object that depends on one or more other objects to define what it is. For example, a Blend Curve depends on the two parent curves that it blends between when it was created (as well as on its two tension parameters).

The NURBSSurface classes describe the properties of NURBS surfaces. As with the NURBSPoint and NURBSCurve classes, depending on the specific class, surfaces can be either independent or dependent. Independent surfaces are those that don't rely on other objects to define their location. Dependent surfaces are surface sub-objects whose geometry depends on other surfaces or curves in the NURBS model. When you change the geometry of the original parent surface or curve, the dependent surface changes as well.


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

Modifying Existing NURBS Objects

Parameter Ranges for Curves and Surfaces

Materials Assignment and Texture Coordinates

Creating NURBS Scene Objects

Creating NURBSCVSurface Values

NURBS Node Properties and Methods


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 Creating NURBS Scene Objects.

As an example, consider the following code fragment that creates a NURBSCVCurve object (with NURBSControlVertex sub-objects) and puts it in the scene:

Example:

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

-- 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 NURBSSet : Value and the addNURBSSet(), breakSurface(), and similar functions defined in NURBS Node Properties and Methods.

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 NURBS Node Properties and Methods. For instance, developers can use the function breakSurface() to take an existing NURBS surface and break it into two separate surfaces.

Non-relational NURBSSets

You can also use the getNURBSSet() function in a non-relational mode, but not supplying the #relational argument, to retrieve a "flattened" version of the NURBSSet in which all dependent surfaces, such as blends and offsets and lofts are represented as independent curves and surfaces and there is no 'live' connection back to the scene object from which the NURBSSet was derived. You might use this to get a simplified version of the NURBS scene object for an export script, for example if the destination system does not support relational objects. You can also use a non-relational NURBSSet derived in this way as the basis for creating other scene objects, perhaps modifying or adding to the set and then re-instantiating it with the NURBSNode() function.


Parameter Ranges for Curves and Surfaces

Methods that deal with points in the parameter space of a curve work with arguments in U. Methods that deal with points in the parameter space of surfaces deal with arguments in U and V. For example, setting the property <NURBSSurfConstPoint>.uParam sets the position of a dependent point in the parent surface's U parameter space. The valid U and V values that may be passed to this method must be obtained by referencing the <NURBSSurface> properties .uParameterRangeMin, .uParameterRangeMax, .vParameterRangeMin, and .vParameterRangeMax on the parent surface. This retrieves the minimum and maximum values for U and V that may be used. For curves there are similar properties for getting the valid range for U.

Developers should be aware that a curve or surface needs to be instantiated in the 3ds max data base before it is okay to call these methods (for example by calling NURBSNode()). Prior to the object existing in the data base these calls will fail.

Generally, when CV curves and surfaces are created, the valid parameter range is known because they were specified in the beginning and ending knot values. In cases where they are not known, one can instantiate a NURBSSet that has just the base curves or surfaces. Once instantiated, the parameter range properties can be interrogated. Then one can build the rest of the parametric model by making additions and/or modifications to the already instantiated object. The node method addNURBSSet() makes this easy to do.


Materials Assignment and Texture Coordinates

Materials and NURBS

Each NURBS surface has its own material ID. If you assign a Multi-SubObject material you can apply a different material to each surface in a NURBS object by setting the <NURBSSurface> property .MatID.

Texture Coordinates and NURBS

Texture coordinates are assigned to each of the four corners of a NURBS surface. On the standard 3ds max primitives for example most are assigned to use (0,0) to (1,1) across the surface. Some primitives, such as the Prism, don't use (0,0) to (1,1) because of the way they wrap. Developers may of course assign any values using the API. The <NURBSSurface> method to do this is setTextureUVs().


Creating NURBS Scene Objects

The following functions create new nodes in the 3ds max scene. The main function is NURBSNode() which takes an arbitrary NURBSSet and instantiates a NURBS object in the scene based on the definition in the NURBSSet. The other two functions are shorthand ways of creating lathe and extrude NURBS surfaces based on existing shapes in the scene.

NURBSNode <nurbsset> {node_creation_parameters}

Takes a NURBSSet object and creates a 3ds max NURBS object in the scene corresponding to the definitions in that NURBSSet. After the function call, the supplied NURBSSet becomes an active representative for the new scene node, all the NURBSId properties are filled-in and you can modify the scene object by modifying the properties of the NURBSSet component objects.

Any of the standard <node> constructor keyword arguments can be added, such as .name, .prefix, .pos, .rotation, .wireColor, etc. See Node class for details.

NURBSLatheNode <curve> <axis> <sweep> [capStart:<boolean>] \

[capEnd:<boolean>] [capType:<integer>] \

[weldCore:<boolean>] [flipNormals:<boolean>] \

[mapCoords:<boolean>] [segs:<integer>] \

[matIDs:<boolean>] [shapeIDs:<boolean>] \

{node_creation_parameters}

This function generates a NURBS object based on the specified lathe (surface of revolution) definition and returns a pointer to it. This is used by the lathe modifier.

curve <node>

The shape object to revolve. Note that if the curve pointed to is a bezier spline then capping won't work properly.

axis <Matrix3>

This specifies the axis of revolution.

sweep <float>

The angle for the surface of revolution in degrees.

capStart: <boolean>

Specifies if the surface should be capped at the beginning: true to cap; false to leave open.

capEnd: <boolean>

Specifies if the surface should be capped at the ending: true to cap; false to leave open.

capType: <integer>

This parameter is not currently used and the value specified is ignored.

weldCore: <boolean>

true to collapse any coincident vertices at the center of the surface; otherwise false.

flipNormals: <boolean>

true to invert the orientation of surface normals; otherwise false.

mapCoords: <boolean>

true to generate mapping coordinates; otherwise false.

segs: <integer>

The number of segments in the surface of revolution.

matIDs: <boolean>

If true special material IDs are assigned to the surfaces and caps.

shapeIDs: <boolean>

If true shape IDs are used. When on, this function uses the material ID values assigned to segments in the spline to be lathed, or curve sub-objects in the NURBS curve to be lathed. This is available only when matIds is true.

NURBSExtrudeNode <shape> <amount> [capStart:<boolean>] \

[capEnd:<boolean>] [capType:<integer>] \

[mapCoords:<boolean>] [matIDs:<boolean>] \

[shapeIDs:<boolean>] {node_creation_parameters}

This function generates a NURBS object based on the specified extrusion definition and returns a pointer to it. This is used by the extrude modifier.

shape <node>

The shape node to extrude. Note that if the shape pointed to is a bezier spline then capping won't work properly.

amount <float>

Specifies the height of the extrusion.

capStart: <boolean>

Specifies if the surface should be capped at the beginning: true to cap; false to leave open.

capEnd: <boolean>

Specifies if the surface should be capped at the ending: true to cap; false to leave open.

capType: <integer>

This parameter is not currently used and the value specified is ignored.

matIDs: <boolean>

If true, special material IDs are assigned to the surfaces and caps.

shapeIDs: <boolean>

If true shape IDs are used. When on, this function uses the material ID values assigned to segments in the spline to be extruded, or curve sub-objects in the NURBS curve to be extruded. This is available only when matIds is true.


Creating NURBSCVSurface Values

The following functions provide shorthand ways to construct NURBSCVSurface values that you can then add to a NURBSSet for creation in the scene.

MakeNURBSLatheSurface <curve> <origin> <north> <start> <end>

This function generates a NURBS surface of revolution given an input curve, origin, up axis, and start and end angles. The output of this function is a NURBS Surface. Note that this is a CV surface that matches the definition, not a relational surface.

curve <NURBSCurve>

This is the NURBS curve that is revolved.

origin <point3>

Specifies the origin of the revolution.

north <point3>

This is the axis that specified the up direction.

start <float>

This is the start angle of the revolution in radians.

end <float>

This is the end angle of the revolution in radians.

MakeNURBSSphereSurface <radius> <center> <north_axis> <ref_axis> \

<startU> <endU> <startV> <endV> [open:<boolean>]

This function generates a NURBS sphere. The output of this function is a NURBS Surface. Note that this is a CV surface that matches the definition, not a relational surface.

radius <float>

The radius of the sphere.

center <Point3>

The center point of origin of the sphere.

north_axis <Point3>

This specifies the up axis. Use (Point3 0 0 1) for the Z axis for example.

ref_Axis <Point3>

This is the direction of the seam. The sphere primitive uses (Point3 0 -1 0) as this value. The northAxis and refAxis must be perpendicular to one another.

startU <float>

The start angle for the sphere in the U direction, specified in radians.

endU <float>

The end angle for the sphere in the U direction, specified in radians.

startV <float>

The start angle for the sphere in the V direction, specified in radians.

endV <float>

The end angle for the sphere in the V direction, specified in radians.

open: <boolean>

If true, the surface is closed; otherwise the surface is not closed. Defaults to false.

MakeNURBSCylinderSurface <radius> <height> <origin> <sym_axis> \

<ref_axis> <start> <end> [open:<boolean>]

This function generates a NURBS cylinder. The output of this function is a NURBS Surface. Note that this is a CV surface that matches the definition, not a relational surface.

radius <float>

The radius of the cylinder.

height <float>

The height of the cylinder.

origin <Point3>

The origin of the cylinder.

sym_Axis <Point3>

The axis of symmetry. The standard cylinder primitive specifies (Point3 0 0 1).

ref_Axis <Point3>

This is the direction of the seam. The standard cylinder primitive specifies (Point3 0 1 0). The symAxis and refAxis must be perpendicular to one another.

start <float>

The start angle in radians.

end <float>

The end angle in radians.

open: <boolean>

If true, the surface is closed; otherwise the surface is not closed. Defaults to false.

MakeNURBSConeSurface <radius1> <radius2> <height> <origin> <sym_axis> \

<ref_axis> <start> <end> [open:<boolean>]

This function generates a NURBS cone surface. The output of this function is a NURBS Surface. Note that this is a CV surface that matches the definition, not a relational surface.

radius1 <float>

One of the radii of the cone.

radius2 <float>

The other radius of the cone.

height <float>

The height of the cone.

origin <Point3>

The origin of the cone.

sym_Axis <Point3>

The axis of symmetry.

ref_Axis <Point3>

This is the direction of the seam. The symAxis and refAxis must be perpendicular to one another.

start <float>

The start angle in radians.

end <float>

The end angle in radians.

open: <boolean>

If true, the surface is closed; otherwise the surface is not closed. Defaults to false.

MakeNURBSTorusSurface <majorRad> <minorRad> <origin> <sym_axis> \

<ref_axis> <startU> <endU> <startV> <endV> \

[open:<boolean>]

This function generates a NURBS torus surface. The output of this function is a NURBS Surface. Note that this is a CV surface that matches the definition, not a relational surface.

Note: This surface is not closed surface.

majorRad <float>

This is the radius of the entire 'donut' shape.

minorRad <float>

The is the radius of the 'tube'.

origin <Point3>

The origin of the cone.

sym_Axis <Point3>

The axis of symmetry.

ref_Axis <Point3>

This is the direction of the seam. The symAxis and refAxis must be perpendicular to one another.

startU <float>

The start angle of the torus in the U direction.

endU <float>

The end angle of the torus in the U direction.

startV <float>

The start angle of the torus in the V direction.

endV <float>

The end angle of the torus in the V direction.

open: <boolean>

If true, the surface is closed; otherwise the surface is not closed. Defaults to false.


NURBS Node Properties and Methods

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, and enable sub-object manipulation in a manner similar to that provided for Editable Meshes.

Methods

The following NURBS-related methods operate on scene nodes:

getNURBSSet <node> [#relational]

This function is used to retrieve a NURBSSet that corresponds to the specified NURBS scene node. This allows access the internal objects inside a 3ds max editable NURBS object.

If the optional #relational parameter is not supplied, the returned NURBSSet will contain only independent curves and surfaces, all dependent objects will be decomposed into corresponding independent objects. So for example, if you pass an object that has a relational model (perhaps two CV surfaces and a dependent blend surface) it will decompose them into three CV surfaces. This will be the CV surfaces that represent the two surfaces and the blend, but you won't have the blend relational data. If the #relational argument is supplied, you get back two CV surfaces and a NURBS blend surface and the NURBSSet is an active representative for the scene object -- any changes you make to the properties of it's constituent NURBSObjects will be reflected directly in the source scene object.

addNURBSSet <node> <nurbsSet>

This function adds the supplied NURBSSet to the specified NURBS scene object, creating subobjects within the scene node corresponding to the definitions in the NURBSSet. After the function call, the supplied NURBSSet becomes an active representative for the new scene node subobjects, all the NURBSId properties are filled-in and you can modify the associated scene sub-object by modifying the properties of the NURBSSet component objects.

transform <node> <nurbsId_or_Id_array> <matrix3>

Transforms the specified sub-objects by the matrix supplied in the node's local space. The sub-objects to be transformed are identified by their NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.

breakCurve <node> <nurbsId> <u_param>

Breaks the specified sub-object curve at the parametric point along the curve defined by the <u_param> float argument. The sub-object to be broken is identified by its NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.

breakSurface <node> <nurbsId> (#U | #V) <u_or_v_param>

Breaks the specified sub-object surface at the parametric point defined by the <u_or_v_param> argument in the u or v direction depending on whether #U or #V is supplied for the third argument. The sub-object to be broken is identified by its NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.

joinCurves <node> <nurbsId1> <nurbsId2> <tolerance_float> \

[flip1:<boolean>] [flip2:<boolean>]

Joins two curve sub-objects in the specified scene node and makes a single curve out of them. That is, the endpoints of the two curve objects are connected by new segments, and the two original curves are replaced by a single curve.

The supplied tolerance is a distance in 3ds max units. If the gap between the curves you are joining is greater than this value, this function creates the join by first creating a blend curve and then joining the three parts. If the gap is less than this value, or if the curves are overlapping or coincident, no blend is created.

Creating a blend and then joining the three curves into a single curve is the better technique. The result matches the parent curves well. Without the blend step, the resulting curve can deviate from the parent curves, in order to maintain smoothness. (The amount of deviation depends on how far from tangent the two input curves were at the join.)

A problem arises when there is a gap but it is too small. In this case, this function generates the blend but because there isn't enough room for it, the resulting curve has a loop in it. To avoid this loop, set this parameter higher than the gap distance.

If you the tolerance to 0.0, the function chooses a value to use for the tolerance.

The sub-objects to be joined are identified by their NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.

joinSurfaces <node> <nurbsId1> <nurbsId2> <edge1_integer> \

<edge2_integer> <tolerance_float>

Joins two surface sub-objects in the specified scene node and makes a single surface from them. The specified edges of the two surface objects are connected by a new surface, and the two original surfaces are replaced by a single surface.

The edges are identified by edge index numbers.

The tolerance is a distance in 3ds max units. If the gap between the surfaces you are joining is greater than this value, this function creates the join by first creating a blend surface. If the gap is less than this value, or if the surfaces are overlapping or coincident, 3ds max doesn't create the blend.

Creating a blend and then joining the three surfaces into a single surface is the better technique. The result matches the parent surfaces well. Without the blend step, the resulting surface can deviate from the parent surfaces, in order to maintain smoothness. (The amount of deviation depends on how far from tangent the two input surfaces were at the join.)

A problem arises when there is a gap but it is too small. In this case, this function generates the blend but because there isn't enough room for it, the resulting surface has a loop in it. To avoid this loop, set the tolerance parameter higher than the gap distance.

If you set the tolerance to 0.0, the function chooses a value to use for the tolerance.

The sub-objects to be joined are identified by their NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.

makeIndependent <node> <nurbsId>

This function takes a dependent sub-object (fillet, offset, blend, etc.) and turns it into a CV variant of itself such that it is independent (no longer dependent on a parent).

The sub-object to be made independent is identified by its NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.

setViewApproximation <node> <surfaceApproximation>

setRenderApproximation <node> <surfaceApproximation>

setSurfaceDisplay <node> <nurbsdisplay>

These methods work NURBS curve and surface scene nodes. They take instances of the NURBSSurfaceApproximation and NURBSDisplay 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.

Associated Methods

canConvertTo <node> <class>

Allows you to test whether a given node is convertible into a given class. Returns true or false. For example:

if canConvertTo $foo NURBSSurface then ...

The kinds of classes you can convert objects to are the generic editable forms including Mesh, SplineShape, NURBSCurve, NURBSSurface, etc.

convertTo <node> <class> -- mapped

This function is a general form of the existing specific conversion functions such as convertToMesh(), convertToSplineShape(), etc. For example, convertToSplineShape() can be written:

convertTo $circle01 SplineShape

If the conversion is not supported, the function returns the value undefined.

convertToNURBSSurface <node> -- mapped

convertToNURBSCurve <node> -- mapped

These functions work on those primitive geometry and shape classes that support conversion to NURBS (such as boxes, spheres, circles, lines, etc.). If an object does not support conversion, the function returns undefined.

isPointSelected <node> <point_index>

Returns true is the specified point is selected, false if not. The definition of a 'point' varies depending on the object type. For meshes, it is the mesh vertex. For a spline, it is the knot. For NURBS objects, it is the vertex or control point.

pointSelection <node> <point_index>

Returns a floating point weighted point selection if the object supports it. Most object types just return 1.0 if the point is selected and 0.0 if not. Only NURBS objects currently support weighted point selection.

stopCreating <node>

This method stops the creation of the current object, if any. This method is primarily used to ensure that a NURBS scene objects is fully created, which it will not be until the creation is stopped. The NURBSSet returned for a NURBS scene object will not be complete if the object is still in creation mode. This method will also deactivated any activated object create buttons in the Create panel.


The NURBS Classes

The following topics describe all of the NURBS classes:

NURBSObject

NURBSPoint : NURBSObject

NURBSCurveConstPoint : NURBSPoint

NURBSCurveIntersectPoint : NURBSPoint

NURBSCurveSurfaceIntersectPoint : NURBSPoint

NURBSIndependentPoint : NURBSPoint

NURBSPointConstPoint : NURBSPoint

NURBSSurfConstPoint : NURBSPoint

NURBSControlVertex : NURBSObject

NURBSCurve : NURBSObject

NURBSBlendCurve : NURBSCurve

NURBSChamferCurve : NURBSCurve

NURBSCVCurve : NURBSCurve

NURBSCurveOnSurface : NURBSCVCurve

NURBSFilletCurve : NURBSCurve

NURBSIsoCurve : NURBSCurve

NURBSMirrorCurve : NURBSCurve

NURBSOffsetCurve : NURBSCurve

NURBSPointCurve : NURBSCurve

NURBSPointCurveOnSurface : NURBSPointCurve

NURBSProjectNormalCurve : NURBSCurve

NURBSProjectVectorCurve : NURBSCurve

NURBSSurfaceEdgeCurve : NURBSCurve

NURBSSurfaceNormalCurve : NURBSCurve

NURBSSurfSurfIntersectionCurve : NURBSCurve

NURBSXFormCurve : NURBSCurve

NURBSSurface : NURBSObject

NURBS1RailSweepSurface : NURBSSurface

NURBS2RailSweepSurface : NURBSSurface

NURBSBlendSurface : NURBSSurface

NURBSCapSurface : NURBSSurface

NURBSCVSurface : NURBSSurface

NURBSExtrudeSurface : NURBSSurface

NURBSFilletSurface : NURBSSurface

NURBSLatheSurface : NURBSSurface

NURBSMirrorSurface : NURBSSurface

NURBSMultiCurveTrimSurface : NURBSSurface

NURBSNBlendSurface : NURBSSurface

NURBSOffsetSurface : NURBSSurface

NURBSPointSurface : NURBSSurface

NURBSRuledSurface : NURBSSurface

NURBSULoftSurface : NURBSSurface

NURBSUVLoftSurface : NURBSSurface

NURBSXFormSurface : NURBSSurface

NURBSTexturePoint : NURBSObject

NURBSDisplay : Value

NURBSSelection : Value

NURBSSet : Value

NURBSSurfaceApproximation : Value

NURBSTextureSurface : Value


NURBSObject Values

This is the parent class for all the NURBS classes and so is not directly constructable.

Properties

Because this is a parent class, all the NURBS classes except NURBSSet have the following properties:

<nurbsobject>.name : string

The name of the NURBS object

<nurbsobject>.index : integer, read-only

Only valid after a NURBSSet is instantiated via NURBSNode() or if the NURBS object is part of a non-relational NURBSSet.

<nurbsobject>.nurbsID : integer, read-only

Only valid after a NURBSSet is instantiated via NURBSNode() or if the NURBS object is part of a relational NURBSSet extracted using getNURBSSet().

<nurbsobject>.selected : boolean

Indicates whether the sub-object in a relational NURBSSet is selected in the NURBS modifier panel in the 3ds max user interface. You can force the selection and deselection of objects by setting this property to true or false.

See also

Value Common Properties, Operators, and Methods


NURBSPoint : NURBSObject

This is the parent class for all the NURBS point classes and so is not directly constructable. The class describes a point in 3D space.

Properties

All NURBS point classes have the following properties. These properties are both gettable and settable for independent points, and read-only for dependent points. They are always given in the parent NURBS node local coordinate system.

<nurbspoint>.pos : point3

<nurbspoint>.x : float

<nurbspoint>.y : float

<nurbspoint>.z : float

See also

NURBSPoint

NURBSObject

Value Common Properties, Operators, and Methods


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.

Constructors

NURBSCurveConstPoint [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbscurveconstpoint>.parent : integer

The parent curve by NURBSet index.

<nurbscurveconstpoint>.parentID : integer

The parent curve by NURBSId.

<nurbscurveconstpoint>.uParam : float

Parametric point along the parent curve.

<nurbscurveconstpoint>.type : #onObject, #offset, #normal, #tangent

Specifies the transform relationship between the point and the curve.

<nurbscurveconstpoint>.offset : point3

Offset vector if an offset type.

<nurbscurveconstpoint>.normal : float

Distance along the normal if a normal type.

<nurbscurveconstpoint>.uTangent : float

Distance along the curve tangent if a tangent type.

<nurbscurveconstpoint>.trimCurve : boolean

If true, trims parent curve at the point.

<nurbscurveconstpoint>.flipTrim : boolean

If true the curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

See also

NURBSPoint

NURBSObject

Value Common Properties, Operators, and Methods


NURBSCurveIntersectPoint : NURBSPoint

This class defines a dependent point at the intersection of two curves.

Constructors

NURBSCurveIntersectPoint [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbscurveintersectpoint>.parent1 : integer

The 1st parent curve by NURBSet index.

<nurbscurveintersectpoint>.parent1ID : integer

The 1st parent curve by NURBSId.

<nurbscurveintersectpoint>.parent2 : integer

The 2nd parent curve by NURBSet index.

<nurbscurveintersectpoint>.parent2ID : integer

The 2nd parent curve by NURBSId.

<nurbscurveintersectpoint>.trimCurve1 : boolean

If true, trim the 1st parent curve at the intersection.

<nurbscurveintersectpoint>.trimCurve2 : boolean

If true, trim the 2nd parent curve at the intersection.

<nurbscurveintersectpoint>.flipTrim1 : boolean

If true the 1st parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

<nurbscurveintersectpoint>.flipTrim2 : boolean

If true the 2nd parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

See also

NURBSPoint

NURBSObject

Value Common Properties, Operators, and Methods


NURBSCurveSurfaceIntersectPoint : NURBSPoint

This class defines a dependent point at the intersection of a curve and a surface.

Constructors

NURBSCurveSurfaceIntersectPoint [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbscurvesurfaceintersectpoint>.parent1 : integer

The parent surface by NURBSet index.

<nurbscurvesurfaceintersectpoint>.parent1ID : integer

The parent surface by NURBSId.

<nurbscurvesurfaceintersectpoint>.parent2 : integer

The parent curve by NURBSet index.

<nurbscurvesurfaceintersectpoint>.parent2ID : integer

The parent curve by NURBSId.

<nurbscurvesurfaceintersectpoint>.trimCurve : boolean

If true, trims parent curve at the point.

<nurbscurvesurfaceintersectpoint>.flipTrim : boolean

If true the curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

<nurbscurvesurfaceintersectpoint>.seed : float

The seed location is a U position along the length of the parent curve.

See also

NURBSPoint

NURBSObject

Value Common Properties, Operators, and Methods


NURBSIndependentPoint : NURBSPoint

This class defines an independent, free-standing point.

Constructors

NURBSIndependentPoint <point3>

getObject <nurbsset> <index>

getPoint <nurbspointsurface> <index>

getPoint <nurbspointcurve> <index>

getPoint <nurbspointcurveonsurface> <index>

operators

<nurbsindependentpoint> == <nurbsindependentpoint>

<nurbsindependentpoint> != <nurbsindependentpoint>

Properties

There are no additional properties for NURBSIndependentPoint.

See also

NURBSPoint

NURBSObject

Value Common Properties, Operators, and Methods


NURBSPointConstPoint : NURBSPoint

This class defines a dependent point that lies at a point or relative to it. It is a point constrained relative to another point. This can be a point used to define a point surface or point curve, it can be a trim point, or just a point in space. There are two ways to specify the displacement of the point's location relative to the U position:

  • OnObject - the point is actually at the parent.

  • Offset - the point is moved according to a relative (object space) X,Y,Z location.

Constructors

NURBSPointConstPoint [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbspointconstpoint>.parent : integer

The parent point by NURBSet index.

<nurbspointconstpoint>.parentID : integer

The parent point by NURBSId.

<nurbspointconstpoint>.type : #onObject, #offset

<nurbspointconstpoint>.offset : point3

Offset vector if an offset type.

See also

NURBSPoint

NURBSObject

Value Common Properties, Operators, and Methods


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.

Constructors

NURBSSurfConstPoint [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbssurfconstpoint>.parent : integer

The parent surface by NURBSet index.

<nurbssurfconstpoint>.parentID : integer

The parent surface by NURBSId.

<nurbssurfconstpoint>.type : #onObject, #offset, #normal, #tangent

<nurbssurfconstpoint>.uParam : float

Parametric position along u direction.

<nurbssurfconstpoint>.vParam : float

Parametric position along v direction.

<nurbssurfconstpoint>.offset : point3

Offset vector if an offset type.

<nurbssurfconstpoint>.normal : float

Distance along the normal if a normal type.

<nurbssurfconstpoint>.uTangent : float

Distance along the u tangent if a tangent type.

<nurbssurfconstpoint>.vTangent : float

Distance along the v tangent if a tangent type.

See also

NURBSPoint

NURBSObject

Value Common Properties, Operators, and Methods


NURBSControlVertex : NURBSObject

This class defines an independent Control Vertex of a NURBS Curve or NURBS Surface. This class shares may of the same properties as a NURBSPoint and has the added property of a rational weight. The weight value of a CV is rational. That is, it is relative to other CVs in the curve or surface. Changing the weight of all CVs at once has no effect, because this doesn't change the ratio between weights.

Constructors

NURBSControlVertex <point3> [<weight_float>]

getCV <nurbscvcurve> <index>

getCV <nurbscvsurface> <u_index> <v_index>

operators

<nurbscontrolvertex> == <nurbscontrolvertex>

<nurbscontrolvertex> != <nurbscontrolvertex>

Properties

<nurbscontrolvertex>.weight : float

The weight of the control vertex. This is a value greater than zero. Larger values cause the CV to have a greater effect, thus the curve or surface will try to pass closer to the CV.

See also

NURBSObject

Value Common Properties, Operators, and Methods


NURBSCurve : NURBSObject

This is the parent class for all the NURBS curve classes and so is not directly constructable. The class describes the common properties of all NURBS curves. This includes its open/closed state, and number of trim points. The evalPos() and evalTangent() methods are used to compute points and tangents on the curve.

Properties

All NURBS curve classes have the following properties:

<nurbscurve>.isClosed : boolean, read-only

true if the curve is closed, false if open.

<nurbscurve>.numTrimPoints : integer, read-only

The number of trim points in the curve.

<nurbscurve>.parameterRangeMin : float, read-only

<nurbscurve>.parameterRangeMax : float, read-only

Contains the minimum and maximum valid values for <u_parm> in the methods associated with NURBS Curves.

<nurbscurve>.matID : integer

The material ID assigned to the curve.

Methods

All NURBS curve classes have the following methods:

evalPos <nurbscurve> <u_param>

Returns the position in space of the given parametric point along the curve.

evalTangent <nurbscurve> <u_param>

Returns the tangent vector at the given parametric point along the curve.

See also

NURBSObject

Value Common Properties, Operators, and Methods


NURBSBlendCurve : NURBSCurve

This class defines a dependent Blend curve. A Blend curve connects the end of one curve to the end of another, blending the curvature of the parents to create a smooth curve between them.

Constructors

NURBSBlendCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsblendcurve>.parent1 : integer

The 1st parent curve by NURBSet index.

<nurbsblendcurve>.parent1ID : integer

The 1st parent curve by NURBSId.

<nurbsblendcurve>.parent2 : integer

The 2nd parent curve by NURBSet index.

<nurbsblendcurve>.parent2ID : integer

The 2nd parent curve by NURBSId.

<nurbsblendcurve>.flip1 : boolean

true to use the end of 1st parent curve; false to use the beginning, defaults to false.

<nurbsblendcurve>.flip2 : boolean

true to use the end of 2nd parent curve; false to use the beginning, defaults to false.

<nurbsblendcurve>.tension1 : float

The tension value for the 1st parent curve.

<nurbsblendcurve>.tension2 : float

The tension value for the 2nd parent curve.

See also

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSChamferCurve : NURBSCurve

This class defines a dependent Chamfer curve. A Chamfer is a curve that creates a straight line corner between two parent curves.

Constructors

NURBSChamferCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbschamfercurve>.parent1 : integer

The 1st parent curve by NURBSet index.

<nurbschamfercurve>.parent1ID : integer

The 1st parent curve by NURBSId.

<nurbschamfercurve>.parent2 : integer

The 2nd parent curve by NURBSet index.

<nurbschamfercurve>.parent2ID : integer

The 2nd parent curve by NURBSId.

<nurbschamfercurve>.length1 : float

The length for 1st parent curve back from the end that defines the beginning of the chamfer.

<nurbschamfercurve>.length2 : float

The length for 2nd parent curve back from the end that defines the beginning of the chamfer.

<nurbschamfercurve>.flip1 : boolean

true to use the end of 1st parent curve; false to use the beginning, defaults to false.

<nurbschamfercurve>.flip2 : boolean

true to use the end of 2nd parent curve; false to use the beginning, defaults to false.

<nurbschamfercurve>.trim1 : boolean

Sets whether 1st parent curve is trimmed. true if the curve is trimmed; otherwise false.

<nurbschamfercurve>.trim2 : boolean

Sets whether 2nd parent curve is trimmed. true if the curve is trimmed; otherwise false.

<nurbschamfercurve>.flipTrim1 : boolean

If true the 1st parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

<nurbschamfercurve>.flipTrim2 : boolean

If true the 2nd parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

See also

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSCVCurve : NURBSCurve

This class defines an independent NURBS CV Curve. The position and weight of the control vertices (CVs) controls the shape of the curve. Unlike spline vertices, CVs don't necessarily lie on the curve they define. The CVs define a control lattice which surrounds the curve.

Constructors

NURBSCVCurve [<property>:<val>] [closed:<boolean>]...

Any of the object's properties may be set via optional keyword arguments on the constructor. If closed:true is specified, the curve is created as a closed curve, otherwise it is an open curve.

getObject <nurbsset> <index>

Properties

<nurbscvcurve>.order : integer

The order of the curve. This is one more than the degree of polynomial of any segment of the curve. All curves have a degree. The degree of a curve is the highest exponent in the equation used to represent it. A linear equation is degree 1, a quadratic equation degree 2. NURBS curves typically are represented by cubic equations and have a degree of 3.

<nurbscvcurve>.numKnots : integer

The number of knots in the curve. If this value is changed, the previous knot data is NOT maintained. Because they are generated mathematically, NURBS curves have a parameter space in addition to the 3D geometric space in which they are displayed. Specifically, an array of values called knots specifies the extent of influence of each control vertex (CV) on the curve or surface.

<nurbscvcurve>.numCVs : integer

The number of control vertices in the curve. If this value is changed, the previous control vertex data is NOT maintained.

<nurbscvcurve>.transform : matrix3

The transformation matrix for the NURBSCVCurve. This controls the relative position of the item within a NURBSSet.

<nurbscvcurve>.endsOverlap : boolean, read-only

true if the ends of the curve overlap even though the curve may not be closed (that is, the tangents match at the ends), false otherwise.

<nurbscvcurve>.autoParam : #notAutomatic, #autoCentripetal, #autoUniform

#notAutomatic, #autoCentripetal, and #autoUniform correspond to the Automatic Reparam options in the CV Curve rollouts: none, chord length and uniform, respectively. Defaults to #notAutomatic.

Methods

close <nurbscvcurve>

Forces the curve to be closed.

getKnot <nurbscvcurve> <index>

setKnot <nurbscvcurve> <index> <float>

Get and set the indexed knot's value, indexes are 1-based. Knots are a mathematical construct that helps define the span of control of CVs and blending functions that define NURBS Curves and Surfaces. The knots are an array of values that determines the parameterization of a curve. Values in the knot vector are nondecreasing. The knots specify the region of influence of the CVs on the curve. It is a way of partitioning the parameter space up into different segments. A B-spline curve or a NURBS curve is a curve that is defined by a series of segments. On each one of the segments the curve is like a polynomial, or in the case of a rational one, it's like the ratio of polynomials. The knot vector describes how to partition the parameter space of the curve up for each of the different pieces of the polynomial.

getCV <nurbscvcurve> <cv_index>

Get the indexed CV as a NURBSControlVertex, indexes are 1-based.

setCV <nurbscvcurve> <cv_index> <NURBSControlVertex>

Sets the indexed CV to the given NURBSControlVertex, indexes are 1-based.

refine <nurbscvcurve> <u_param>

Add a new, interpolated CV at the given parametric point along the curve.

reparameterize <nurbscvcurve> (#centripetal | #uniform)

Reparameterizes the curve by chord length (#centripetal) or uniform (#uniform) uniform parameterization.

Notes

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

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSCurveOnSurface : NURBSCVCurve

This class defines a dependent Curve-on-Surface CV curve. These curves can be used for trimming the surface they lie on.

Constructors

NURBSCurveOnSurface [<property>:<val>] [closed:<boolean>]...

Any of the object's properties may be set via optional keyword arguments on the constructor. If closed:true is specified, the curve is created as a closed curve, otherwise it is an open curve.

getObject <nurbsset> <index>

Properties

<nurbscurveonsurface>.parent : integer

The parent surface by NURBSet index.

<nurbscurveonsurface>.parentID : integer

The parent surface by NURBSId.

<nurbscurveonsurface>.trim : boolean

If true, trims parent surface at the curve.

<nurbscurveonsurface>.flipTrim : boolean

The state of the trim flip toggle. This controls which portion of the surface is trimmed.

Notes

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.

See Also

NURBSCVCurve

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSFilletCurve : NURBSCurve

This class defines a dependent Fillet curve. A Fillet is a curve that creates a circular arc corner between two parent curves.

Constructors

NURBSFilletCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsfilletcurve>.parent1 : integer

The 1st parent curve by NURBSet index.

<nurbsfilletcurve>.parent1ID : integer

The 1st parent curve by NURBSId.

<nurbsfilletcurve>.parent2 : integer

The 2nd parent curve by NURBSet index.

<nurbsfilletcurve>.parent2ID : integer

The 2nd parent curve by NURBSId.

<nurbsfilletcurve>.radius : float

The radius of the fillet.

<nurbsfilletcurve>.flip1 : boolean

true to use the end of 1st parent curve; false to use the beginning, defaults to false.

<nurbsfilletcurve>.flip2 : boolean

true to use the end of 2nd parent curve; false to use the beginning, defaults to false.

<nurbsfilletcurve>.trim1 : boolean

Sets whether 1st parent curve is trimmed. true if the curve is trimmed; otherwise false.

<nurbsfilletcurve>.trim2 : boolean

Sets whether 2nd parent curve is trimmed. true if the curve is trimmed; otherwise false.

<nurbsfilletcurve>.flipTrim1 : boolean

If true the 1st parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

<nurbsfilletcurve>.flipTrim2 : boolean

If true the 2nd parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

See also

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSIsoCurve : NURBSCurve

This class defines a dependent Iso (isoparametric) curve. U and V Iso curves are dependent curves created along lines of constant parameter value of a NURBS surface.

Constructors

NURBSIsoCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsisocurve>.parent : integer

The parent surface by NURBSet index.

<nurbsisocurve>.parentID : integer

The parent surface by NURBSId.

<nurbsisocurve>.dir : #U, #V

The direction of the iso curve, either #U or #V.

<nurbsisocurve>.parameter : float

The parametric position in the range of 0.0 to 1.0 in the given direction on the surface at which the iso line will sit.

<nurbsisocurve>.trim : boolean

If true, trims parent surface at the curve.

<nurbsisocurve>.flipTrim : boolean

The state of the trim flip toggle. This controls which portion of the surface is trimmed.

<nurbsisocurve>.seed : point2

The seed location is a UV position on the parent surface.

See also

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSMirrorCurve : NURBSCurve

This class defines a dependent Mirror curve. A Mirror curve is similar to a mirror object that you create using the Mirror tool (on the 3ds max toolbar) or the Mirror modifier. It is the original curve reflected about one or two axes.

Constructors

NURBSMirrorCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsmirrorcurve>.parent : integer

The parent curve by NURBSet index.

<nurbsmirrorcurve>.parentID : integer

The parent curve by NURBSId.

<nurbsmirrorcurve>.axis : #X, #Y, #Z, #XY, #XZ, #YZ

The axis or axes of reflection for the curve.

<nurbsmirrorcurve>.distance : float

The mirror offset distance.

<nurbsmirrorcurve>.transform : matrix3

This is an additional transformation applied to the axis specification. This corresponds to the gizmo the user may use interactively to alter the location of the mirror axis. This is exactly equivalent to setting the transform on the gizmo of a mirror modifier.

See also

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSOffsetCurve : NURBSCurve

This class defines a dependent Offset curve. An Offset curve is offset from the original, parent curve. It lies in the same plane as its parent, and is normal to the original.

Constructors

NURBSOffsetCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsoffsetcurve>.parent : integer

The parent curve by NURBSet index.

<nurbsoffsetcurve>.parentID : integer

The parent curve by NURBSId.

<nurbsoffsetcurve>.distance : float

The distance of the offset curve from the parent.

See also

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSPointCurve : NURBSCurve

This class defines an independent curve that uses points to describe its shape. All the points lie on the curve itself.

Constructors

NURBSPointCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbspointcurve>.numPoints : integer

The number of points in the point curve. If this value is changed, the previous point data is not maintained.

<nurbspointcurve>.closed : boolean

true if the curve is closed, false if open.

<nurbspointcurve>.transform : matrix3

The transformation matrix for the NURBSPointCurve. This controls the relative position of the item within a NURBSSet.

Methods

close <nurbspointcurve>

Closes the curve.

getPoint <nurbspointcurve> <index>

Get the indexed curve point as a NURBSIndependentPoint

setPoint <nurbspointcurve> <index> <nurbs_independent_pt>

Set the indexed point to the given NURBSIndependentPoint

refine <nurbspointcurve> <u_param>

Adds a new, interpolated point at the given parametric position along the curve.

See also

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSPointCurveOnSurface : NURBSPointCurve

This class defines a dependent Curve-on-Surface Point curve. These curves can be used for trimming the surface they lie on.

Constructors

NURBSPointCurveOnSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbspointcurveonsurface>.parent : integer

The parent surface by NURBSet index.

<nurbspointcurveonsurface>.parentID : integer

The parent surface by NURBSId.

<nurbspointcurveonsurface>.trim : boolean

If true, trims parent surface at the curve.

<nurbspointcurveonsurface>.flipTrim : boolean

The state of the trim flip toggle. This controls which portion of the surface is trimmed.

See also

NURBSPointCurve

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSProjectNormalCurve : NURBSCurve

This class defines a dependent Normal Projected curve. A Normal Projected curve lies on a surface. It is based on an existing curve, which is projected onto the surface in the direction of the surface's normals.

Constructors

NURBSProjectNormalCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsprojectnormalcurve>.parent1 : integer

The parent surface by NURBSet index.

<nurbsprojectnormalcurve>.parent1ID : integer

The parent surface by NURBSId.

<nurbsprojectnormalcurve>.parent2 : integer

The parent curve by NURBSet index.

<nurbsprojectnormalcurve>.parent2ID : integer

The parent curve by NURBSId.

<nurbsprojectnormalcurve>.trim : boolean

If true, trims parent surface at the curve.

<nurbsprojectnormalcurve>.flipTrim : boolean

The state of the trim flip toggle. This controls which portion of the surface is trimmed.

<nurbsprojectnormalcurve>.seed : point2

The seed location is a UV position on the parent surface.

See also

NURBSPointCurve

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSProjectVectorCurve : NURBSCurve

This class defines a dependent Vector Projected curve. A Vector Projected curve lies on a surface. This is almost the same as a Normal Projected curve, except that the projection from the existing curve to the surface is in the direction of a vector that you can control.

Constructors

NURBSProjectVectorCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsprojectvectorcurve>.parent1 : integer

The parent surface by NURBSet index.

<nurbsprojectvectorcurve>.parent1ID : integer

The parent surface by NURBSId.

<nurbsprojectvectorcurve>.parent2 : integer

The parent curve by NURBSet index.

<nurbsprojectvectorcurve>.parent2ID : integer

The parent curve by NURBSId.

<nurbsprojectvectorcurve>.trim : boolean

If true, trims parent surface at the curve.

<nurbsprojectvectorcurve>.flipTrim : boolean

The state of the trim flip toggle. This controls which portion of the surface is trimmed.

<nurbsprojectvectorcurve>.seed : point2

The seed location is a UV position on the parent surface.

<nurbsprojectvectorcurve>.pVec : point3

The projection vector.

See also

NURBSPointCurve

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSSurfaceEdgeCurve : NURBSCurve

This class defines a dependent Surface Edge curve.

Constructors

NURBSSurfaceEdgeCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbssurfaceedgecurve>.parent : integer

The parent surface by NURBSet index.

<nurbssurfaceedgecurve>.parentID : integer

The parent surface by NURBSId.

<nurbssurfaceedgecurve>.seed : Point2

The seed location is a UV position on the parent surface.

See also

NURBSPointCurve

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSSurfaceNormalCurve : NURBSCurve

This class defines a dependent Surface Normal curve. This is a curve created at a specified distance from a surface and normal to it.

Constructors

NURBSSurfaceNormalCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbssurfacenormalcurve>.parent : integer

The parent curve by NURBSet index.

<nurbssurfacenormalcurve>.parentID : integer

The parent curve by NURBSId.

<nurbssurfacenormalcurve>.distance : float

The distance along the normal from the surface to the curve.

Notes

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

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSSurfSurfIntersectionCurve : NURBSCurve

This class defines a dependent Surface-Surface Intersection curve.

Constructors

NURBSSurfSurfIntersectionCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbssurfsurfintersectioncurve>.parent1 : integer

The 1st parent surface by NURBSet index.

<nurbssurfsurfintersectioncurve>.parent1ID : integer

The 1st parent surface by NURBSId.

<nurbssurfsurfintersectioncurve>.parent2 : integer

The 2nd parent surface by NURBSet index.

<nurbssurfsurfintersectioncurve>.parent2ID : integer

The 2nd parent surface by NURBSId.

<nurbssurfsurfintersectioncurve>.trimCurve1 : boolean

If true, trim the 1st parent surface at the intersection.

<nurbssurfsurfintersectioncurve>.trimCurve2 : boolean

If true, trim the 2nd parent surface at the intersection.

<nurbssurfsurfintersectioncurve>.flipTrim1 : boolean

If true the 1st parent surface is trimmed from the point towards low parameter space. If false the surface is trimmed from the point towards high parameter space.

<nurbssurfsurfintersectioncurve>.flipTrim2 : boolean

If true the 2nd parent surface is trimmed from the point towards low parameter space. If false the surface is trimmed from the point towards high parameter space.

<nurbssurfsurfintersectioncurve>.seed : point2

The seed location is a UV position on the parent surface.

See also

NURBSPointCurve

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSXFormCurve : NURBSCurve

This class defines a dependent Transform (XForm) curve. A Transform curve is a copy of the original curve with a different position, rotation, or scale.

Constructors

NURBSXFormCurve [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsxformcurve>.parent : integer

The parent curve by NURBSet index.

<nurbsxformcurve>.parentID : integer

The parent curve by NURBSId.

<nurbsxformcurve>.transform : matrix3

The offset transformation matrix for the NURBSCVCurve. This controls the relative position of the item to the parent curve.

See also

NURBSPointCurve

NURBSCurve

NURBSObject

Value Common Properties, Operators, and Methods


NURBSSurface : NURBSObject

This is the parent class for all the NURBS surface classes and so is not directly constructable. The class describes the common properties of all NURBS surfaces. This includes its material ID, texture/tiling options, renderable state, and open/closed state, and normal inverted state. The evalPos(), evalUTangent(), and evalVTangent() methods are used to compute points and tangents on the surface.

Properties

All NURBS surface classes have the following properties.

<nurbssurface>.renderable : boolean

Specifies whether the surface is renderable. true if the surface is renderable, false if not.

<nurbssurface>.flipNormals : boolean

Specifies whether all the surface's surface normals are flipped. true if the surface normals are to be flipped, false if not.

<nurbssurface>.generateUVs1 : boolean

If true, enables the generation of UV mapping coordinates for UVW channel 1. See the getGenerateUVs() and setGenerateUVs() methods for generalized mapping channel access.

<nurbssurface>.generateUVs2 : boolean

If true, enables the generation of UV mapping coordinates for UVW channel 2. See the getGenerateUVs() and setGenerateUVs() methods for generalized mapping channel access.

<nurbssurface>.matID : integer

The material ID of the surface.

<nurbssurface>.closedInU : boolean, read-only

true if the surface is closed in the U direction, false if open.

<nurbssurface>.closedInV : boolean, read-only

true if the surface is closed in the V direction, false if open.*

<nurbssurface>.uParameterRangeMin : float, read-only

<nurbssurface>.uParameterRangeMax : float, read-only

Contains the minimum and maximum valid values for <u_parm> in the methods associated with NURBS Surfaces.

<nurbssurface>.vParameterRangeMin : float, read-only

<nurbssurface>.vParameterRangeMax : float, read-only

Contains the minimum and maximum valid values for <v_param> in the methods associated with NURBS Surfaces.

<nurbssurface>.textureSurface1 : NURBSTextureSurface

<nurbssurface>.textureSurface2 : NURBSTextureSurface

Used to get and set the texture surfaces for the two mapping channels. These properties take and return instances of the NURBSTextureSurface class. .textureSurface1 accesses mapping channel 1 and .textureSurface2 accesses mapping channel 2. See NURBSTextureSurface : Value. See the getTextureSurface() and setTextureSurface() methods for generalized mapping channel access.

It is not possible to assign texture surfaces to NURBS objects present in the scene. You can create new NURBSSets and the texture surface is used when you call createNURBSObject(). However, if you do a getNURBSSet() and assign a NURBSTextureSurface to these properties, nothing happens.

Methods

All NURBS surface classes have the following methods:

evalPos <nurbssurface> <u_param> <v_param>

Returns the coordinates in space of the point at the given U and V parametric position on the surface.

evalUTangent <nurbssurface> <u_param> <v_param>

Returns the U tangent vector of the surface at the given U and V parametric position on the surface.

evalVTangent <nurbssurface> <u_param> <v_param>

Returns the V tangent vector of the surface at the given U and V parametric position on the surface.

getTiling <nurbssurface> [channel:<index>]

setTiling <nurbssurface> <ut> <vt> [channel:<index>]

These methods get and set the tiling factor on the surface in the u and v directions. These methods return or take a point2 value, with u tiling in the x component and v tiling in the y component of the point2. The optional channel keyword argument can be used to select the mapping channel which defaults to 1.

getTilingOffset <nurbssurface> [channel:<index>]

setTilingOffset <nurbssurface> <uo> <vo> [channel:<index>]

These methods get and set the tiling offset on the surface for the selected channel. These methods return or take a point2 value, with u offset in the x component and v offset in the y component of the point2. The optional channel keyword argument can be used to select the mapping channel which defaults to 1.

getGenerateUVs <nurbssurface> <channel_index>

setGenerateUVs <nurbssurface> <channel_index> <boolean>

These methods get and set whether the generation of UV mapping coordinates for the selected channel is enabled.

getTextureUVs <nurbssurface> <index> [channel:<index>]

setTextureUVs <nurbssurface> <index> <point2> [channel:<index>]

These methods get and set the texture UV as a point2 value for the indexed coordinate and selected channel. The 1-based index of the texture coordinate must be >= 1 and <= 4. The optional channel keyword argument can be used to select the mapping channel which defaults to 1.

getTextureSurface <nurbssurface> <channel_index>

setTextureSurface <nurbssurface> <channel_index> <NURBSTextureSurface>

These methods get and set texture surfaces for the selected channel. These methods return or take an instance of the NURBSTextureSurface class. See NURBSTextureSurface : Value.

getProdTess <nurbssurface> <tessType_name>

setProdTess <nurbssurface> <tessType_name> <NURBSSurfaceApproximation>

getViewTess <nurbssurface> <tessType_name>

setViewTess <nurbssurface> <tessType_name> <NURBSSurfaceApproximation>

These methods get and set renderer and viewport NURBSSurfaceApproximation values for individual surfaces, where <tessType_name> is one of #surface, #displacement, or #curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.

clearProdTess <nurbssurface> <tessType_name>

clearViewTess <nurbssurface> <tessType_name>

Resets the surface approximation settings for the surface for the given tessellation type, where <tessType_name> is one of #surface, #displacement, or #curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.

See also

NURBSObject

Value Common Properties, Operators, and Methods


NURBS1RailSweepSurface : NURBSSurface

This class defines a dependent 1-Rail Sweep surface. A 1-Rail Sweep surface uses at least two curves. One curve, the "rail," defines one edge of the surface. The other curves define the surface's cross sections. The cross-section curves should intersect the rail curve. If the cross sections don't intersect the rail, the resulting surface is unpredictable.

Constructors

NURBS1RailSweepSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbs1railsweepsurface>.rail : integer

The parent rail curve by NURBSet index.

<nurbs1railsweepsurface>.railID : integer

The parent rail curve by NURBSId.

<nurbs1railsweepsurface>.numCurves : integer

The number of cross-section curves.

<nurbs1railsweepsurface>.parallel : boolean

If true, ensures that the sweep surface's normal is parallel to the rail.

<nurbs1railsweepsurface>.axisTM : matrix3

The axis of the sweep.

Methods

appendCurve <nurbs1railsweepsurface> <curve> [flip:<boolean>] [startPoint:<float>]

Adds a curve to the end of the list of cross-section curves by specifying the index in the NURBSSet. If flip:true is specified, the cross-section curve is reversed. startPoint specifies the start point on the parent curve. startPoint is applicable only if the parent is a closed curve.

appendCurveByID <nurbs1railsweepsurface> <curveID> [flip:<boolean>] [startPoint:<float>]

Adds a curve to the end of the list of cross-section curves by specifying the NURBSId. If flip:true is specified, the cross-section curve is reversed. startPoint specifies the start point on the parent curve. startPoint is applicable only if the parent is a closed curve.

getCurve <nurbs1railsweepsurface> <index>

setCurve <nurbs1railsweepsurface> <index> <curve>

Get or set the indexed cross-section curve by NURBSSet index.

getCurveID <nurbs1railsweepsurface> <index>

setCurveByID <nurbs1railsweepsurface> <index> <curveID>

Get or set the indexed cross-section curve by NURBSId.

getFlip <nurbs1railsweepsurface> <index>

setFlip <nurbs1railsweepsurface> <index> <boolean>

Get or set whether the indexed cross-section curve is reversed.

getCurveStartPoint <nurbs1railsweepsurface> <index>

setCurveStartPoint <nurbs1railsweepsurface> <index> <float>

Get or set the start point of the indexed cross-section curve on the parent curve. The start point is applicable only if the parent is a closed curve.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBS2RailSweepSurface : NURBSSurface

This class defines a dependent 2-Rail Sweep surface. A 2-Rail Sweep surface uses at least three curves. Two curves, the "rails," define the two edges of the surface. The other curves define the surface's cross sections. A 2-Rail Sweep surface is similar to a 1-Rail sweep. The additional rail gives you more control over the shape of the surface.

Constructors

NURBS2RailSweepSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbs2railsweepsurface>.rail1 : integer

The 1st parent rail curve by NURBSet index.

<nurbs2railsweepsurface>.rail1ID : integer

The 1st parent rail curve by NURBSId.

<nurbs2railsweepsurface>.rail2 : integer

The 2nd parent rail curve by NURBSet index.

<nurbs2railsweepsurface>.rail2ID : integer

The 2nd parent rail curve by NURBSId.

<nurbs2railsweepsurface>.numCurves : integer

The number of cross-section curves.

<nurbs2railsweepsurface>.parallel : boolean

If false, the rail curves define a ruled surface, and the cross sections describe lofting from this base ruled surface. If true, each cross section is associated with its best fitting plane. This plane moves along the rails and parallel to them. If the rails are curved, the plane can rotate. If the spacing between the rails changes, the section scales or stretches. In either case, the surface is blended from section to section along its entire length.

Methods

appendCurve <nurbs2railsweepsurface> <curve> [flip:<boolean>] [startPoint:<float>]

Adds a curve to the end of the list of cross-section curves by specifying the index in the NURBSSet. If flip:true is specified, the cross-section curve is reversed. startPoint specifies the start point on the parent curve. startPoint is applicable only if the parent is a closed curve.

appendCurveByID <nurbs2railsweepsurface> <curveID> [flip:<boolean>] [startPoint:<float>]

Adds a curve to the end of the list of cross-section curves by specifying the NURBSId. If flip:true is specified, the cross-section curve is reversed. startPoint specifies the start point on the parent curve. startPoint is applicable only if the parent is a closed curve.

getCurve <nurbs2railsweepsurface> <index>

setCurve <nurbs2railsweepsurface> <index> <curve>

Get or set the indexed cross-section curve by NURBSSet index.

getCurveID <nurbs2railsweepsurface> <index>

setCurveByID <nurbs2railsweepsurface> <index> <curveID>

Get or set the indexed cross-section curve by NURBSId.

getFlip <nurbs2railsweepsurface> <index>

setFlip <nurbs2railsweepsurface> <index> <boolean>

Get or set whether the indexed cross-section curve is reversed.

getCurveStartPoint <nurbs2railsweepsurface> <index>

setCurveStartPoint <nurbs2railsweepsurface> <index> <float>

Get or set the start point of the indexed cross-section curve on the parent curve. The start point is applicable only if the parent is a closed curve.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSBlendSurface : NURBSSurface

This class defines a dependent Blend surface. A Blend surface connects the edge of one surface to the edge of another, blending the curvature of the parents to create a smooth surface between them. You can also blend from a surface to a curve, or from a curve to a curve.

Constructors

NURBSBlendSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsblendsurface>.parent1 : integer

The 1st parent by NURBSet index.

<nurbsblendsurface>.parent1ID : integer

The 1st parent by NURBSId.

<nurbsblendsurface>.parent2 : integer

The 2nd parent by NURBSet index.

<nurbsblendsurface>.parent2ID : integer

The 2nd parent by NURBSId.

<nurbsblendsurface>.edge1 : integer

Which edge of the 1st parent surface is used for the blend. The property's value is one of the following:

1: The low U edge

2: The high U edge

3: The low V edge

4: The high V edge

<nurbsblendsurface>.edge2 : integer

Which edge of the 2nd parent surface is used for the blend.

<nurbsblendsurface>.flip1 : boolean

Controls the matching of parent surface normals when creating the Blend surface. For example, normally when you create a Blend surface between two parent surfaces you don't want a 'bow tie' surface (one with the ends rotated 180 degrees so it crosses on itself in the middle). If you simply match the parent normals you'll occasionally get a 'bow tie' surface. To prevent this you use this property to set a state indicating that one or the other should be flipped before it's used. In this way, when the blend is created, a 'bow tie' won't occur. If true, the 1st parent's surface normal will be matched; if false the 1st parent's surface normal will not be matched.

<nurbsblendsurface>.flip2 : boolean

If true, the 2nd parent's surface normal will be matched; if false the 2nd parent's surface normal will not be matched.

<nurbsblendsurface>.tension1 : float

The tension value for the 1st parent.

<nurbsblendsurface>.tension2 : float

The tension value for the 2nd parent.

<nurbsblendsurface>.curveStartPoint1 : float

<nurbsblendsurface>.curveStartPoint2 : float

Adjusts the position of the start point at the two edges of the blend. Adjusting the start points can help eliminate unwanted twists or "buckles" in the surface. These values are not applicable if the edges or curves are not closed.

Methods

getParent <nurbsblendsurface> <index>

setParent <nurbsblendsurface> <index> <curve>

Get or set a parent by NURBSSet index. <index> = 1 - parent 1; 2 - parent 2.

getParentID <nurbsblendsurface> <index>

setParentID <nurbsblendsurface> <index> <curveID>

Get or set a parent by NURBSId. <index> = 1 - parent 1; 2 - parent 2.

getEdge <nurbsblendsurface> <index>

setEdge <nurbsblendsurface> <index> <edge>

Get or set which edge of the parent surface is used for the blend. <index> = 1 - parent 1; 2 - parent 2. See the edge1 property description for the <edge> value description.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSCapSurface : NURBSSurface

This class defines a dependent Cap surface. A Cap surface is a surface that caps a closed curve or the edge of a closed surface. Caps are especially useful with extruded surfaces.

Constructors

NURBSCapSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbscapsurface>.parent : integer

The parent curve or surface by NURBSet index.

<nurbscapsurface>.parentID : integer

The parent curve or surface by NURBSId.

<nurbscapsurface>.edge : integer

Which edge of the parent surface is capped. This value is not applicable if the parent is a curve. The property's value is one of the following:

1: The low U edge

2: The high U edge

3: The low V edge

4: The high V edge

<nurbscapsurface>.curveStartPoint : integer

The start point on the parent curve. This value is only applicable if the parent is a curve.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSCVSurface : NURBSSurface

This class defines an independent surface that uses control vertices (CVs) to describe its shape. The CVs define a control lattice which surrounds the surface.

Constructors

NURBSCVSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbscvsurface>.uOrder : integer

<nurbscvsurface>.vOrder : integer

The order of the surface in the U and V directions.

<nurbscvsurface>.numUKnots : integer

<nurbscvsurface>.numVKnots : integer

The number of knots in the surface in the U and V directions. If this value is changed, the previous knot data is NOT maintained. Because they are generated mathematically, NURBS surfaces have a parameter space in addition to the 3D geometric space in which they are displayed. Specifically, an array of values called knots specifies the extent of influence of each control vertex (CV) on the surface.

<nurbscvsurface>.numCVs : point2

The number of control vertices for the surface in the U and V directions. If this value is changed, the previous control vertex data is NOT maintained.

<nurbscvsurface>.transform : matrix3

The transformation matrix for the NURBSCVSurface. This controls the relative position of the item within a NURBSSet.

<nurbscvsurface>.uEdgesOverlap : boolean, read-only

<nurbscvsurface>.vEdgesOverlap : boolean, read-only

true if the edges of the surface overlap in U and/or V even though the surface may not be closed (that is, the tangents match at the edges), false otherwise.

<nurbscvsurface>.autoParam : #notAutomatic, #autoCentripetal, #autoUniform

#notAutomatic, #autoCentripetal, and #autoUniform correspond to the Automatic Reparam options in the CV Surface rollouts: none, chord length and uniform, respectively. Defaults to #notAutomatic.

<nurbscvsurface>.rigid : boolean

true if the surface is 'rigid'; otherwise false. The only editing allowed on a rigid surface is to transform it at the Surface sub-object level. You can't move a rigid surface's points or CVs, or change the number of points or CVs. Rigid surfaces reduce the amount of memory used by the NURBS model. Making surfaces rigid improves performance, especially for large and complex models. When a surface is rigid, you can't see its points or CVs when you are at the Point or Surface CV sub-object levels. If the model has no nonrigid surfaces and no point curves, the Point and Surface CV sub-object levels aren't available at all.

Methods

closeU <nurbscvsurface>

Closes the surface in the U direction.

closeV <nurbscvsurface>

Closes the surface in the V direction.

getUKnot <nurbscvsurface> <u_index>

Get the indexed U-direction knot; knot indexes are 1-based.

setUKnot <nurbscvsurface> <u_index> <float>

Sets the indexed U-direction knot to the given value; knot indexes are 1-based.

getVKnot <nurbscvsurface> <v_index>

Get the indexed V-direction knot; knot indexes are 1-based.

setVKnot <nurbscvsurface> <v_index> <float>

Get the indexed V-direction knot to the given value; knot indexes are 1-based.

getCV <nurbscvsurface> <u_index> <v_index>

Get the CV at the given U and V index as a NURBSControlVertex; CV indexes are 1-based.

setCV <nurbscvsurface> <u_index> <v_index> <NURBSControlVertex>

Sets the CV at the given U and V index to the supplied NURBSControlVertex; CV indexes are 1-based.

refineU <nurbscvsurface> <v_param>

Adds new row of interpolated CVs in the U direction on the surface at the given parametric V point.

refineV <nurbscvsurface> <u_param>

Adds new column of interpolated CVs in the V direction on the surface at the given parametric U point.

refine <nurbscvsurface> <u_param> <v_param>

Adds a new row and column of interpolated CVs on the surface at the given parametric UV position.

reparameterize <nurbscvsurface> (#centripetal | #uniform)

Reparameterizes the surface by chord length (#centripetal) or uniform (#uniform) uniform parameterization.

Notes

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

NURBSObject

Value Common Properties, Operators, and Methods


NURBSExtrudeSurface : NURBSSurface

This class defines a dependent Extrude surface. An Extrude surface is extruded from a curve sub-object. It is similar to a surface created with the Extrude modifier. The advantage is that an extrude sub-object is part of the NURBS model, so you can use it to construct other curve and surface sub-objects.

Constructors

NURBSExtrudeSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsextrudesurface>.parent : integer

The parent curve by NURBSet index.

<nurbsextrudesurface>.parentID : integer

The parent curve by NURBSId.

<nurbsextrudesurface>.distance : float

The length of extrusion.

<nurbsextrudesurface>.axisTM : matrix3

The extrusion axis.

<nurbsextrudesurface>.curveStartPoint : float

The start point on the parent curve. This value is only applicable if the curve is closed.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSFilletSurface : NURBSSurface

This class defines a dependent Fillet surface. A Fillet surface is a rounded corner surface connecting the edges of two other surfaces.

Constructors

NURBSFilletSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsfilletsurface>.cubic : boolean

If true, the radius is always linear. If false, the radius is treated as a cubic function, allowing it to change based on the parent surfaces' geometry.

Methods

getParent <nurbsfilletsurface> <index>

setParent <nurbsfilletsurface> <index> <curve>

Get or set a parent surface by NURBSSet index. <index> = 1 - parent 1; 2 - parent 2.

setParentID <nurbsfilletsurface> <index> <curveID>

getParentID <nurbsfilletsurface> <index>

Get or set a parent surface by NURBSId. <index> = 1 - parent 1; 2 - parent 2.

getSeed <nurbsfilletsurface> <index>

setSeed <nurbsfilletsurface> <index> <point2>

The UV location of the seed value on a parent surface. <index> = 1 - parent 1; 2 - parent 2.

getRadius <nurbsfilletsurface> <index>

setRadius <nurbsfilletsurface> <index> <float>

Get or set the radius of the fillet surface. <index> = 1 - start radius; 2 - end radius.

getTrimSurface <nurbsfilletsurface> <index>

setTrimSurface <nurbsfilletsurface> <index> <bool>

Get or set whether to trim a parent's surface. If true, trims the parent surface at the intersection. <index> = 1 - parent 1; 2 - parent 2.

getFlipTrim <nurbsfilletsurface> <index>

setFlipTrim <nurbsfilletsurface> <index> <bool>

Get or set the direction to trim a parent's surface. If true the parent surface is trimmed from the point towards low parameter space. If false the surface is trimmed from the point towards high parameter space. <index> = 1 - parent 1; 2 - parent 2.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSLatheSurface : NURBSSurface

This class defines a dependent Lathe surface. A Lathe surface is generated from a curve sub-object. It is similar to a surface created with the Lathe modifier. The advantage is that a lathe sub-object is part of the NURBS model, so you can use it to construct other curve and surface sub-objects.

Constructors

NURBSLatheSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbslathesurface>.parent : integer

The parent curve by NURBSet index.

<nurbslathesurface>.parentID : integer

The parent curve by NURBSId.

<nurbslathesurface>.axisTM : matrix3

The axis system for the surface of revolution.

<nurbslathesurface>.sweep : float

The angle of the revolution in degrees.

<nurbsextrudesurface>.curveStartPoint : float

The start point on the parent curve. This value is only applicable if the curve is closed.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSMirrorSurface : NURBSSurface

This class defines a dependent Mirror surface. A Mirror surface is similar to a mirror object that you create using the Mirror tool (on the 3ds max toolbar) or the Mirror modifier. It is the original surface reflected about one or two axes.

Constructors

NURBSMirrorSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsmirrorsurface>.parent : integer

The parent curve by NURBSet index.

<nurbsmirrorsurface>.parentID : integer

The parent curve by NURBSId.

<nurbsmirrorsurface>.axis : #X, #Y, #Z, #XY, #XZ, #YZ

The axis or axes of reflection for the surface.

<nurbsmirrorsurface>.distance : float

The offset from the center of the local coordinate system for the mirror object that moves the mirror, in the direction specified by the mirror axis.

<nurbsmirrorsurface>.transform : matrix3

This is an additional transformation applied to the axis specification. This corresponds to the gizmo the user may use interactively to alter the location of the mirror axis. This is exactly equivalent to setting the transform on the gizmo of a mirror modifier.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSMultiCurveTrimSurface : NURBSSurface

This class defines a dependent Multicurve Trim surface which is a surface that is trimmed by multiple curves forming a loop.

Constructors

NURBSMultiCurveTrimSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsmulticurvetrimsurface>.surfaceParent : Integer

The parent surface by NURBSet index.

<nurbsmulticurvetrimsurface>.surfaceParentID : Integer

The parent surface by NURBSId.

<nurbsmulticurvetrimsurface>.numCurves : Integer

The number of curves used for the trim loop.

<nurbsmulticurvetrimsurface>.flipTrim : Boolean

The state of the trim flip toggle. This controls which portion of the surface is trimmed.

Methods

getParent <nurbsmulticurvetrimsurface> <index>

Gets the NURBSSet index of the indexed trim loop.

setParent <nurbsmulticurvetrimsurface> <index> <curve>

Sets the indexed trim loop to the curve specified by the NURBSSet index.

getParentID <nurbsmulticurvetrimsurface> <index>

Gets the NURBSId of the indexed trim loop.

setParentID <nurbsmulticurvetrimsurface> <index> <curveID>

Sets the indexed curve in the trim loop to the curve specified by the NURBSId.

appendCurve <nurbsmulticurvetrimsurface> <curve>

Adds a curve to the end of the list of curves comprising the trim loop by specifying the NURBSSet index.

appendCurveByID <nurbsmulticurvetrimsurface> <curveID>

Adds a curve to the end of the list of curves comprising the trim loop by specifying the NURBSId.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSNBlendSurface : NURBSSurface

This class defines a dependent Multisided Blend surface. A Multisided Blend surface is a surface that "fills in" the edges defined by three or four other curve or surfaces. Unlike a regular, two-sided Blend surface, the curves or surfaces edges must form a closed loop (that is, sequence head to tail, and the ends must match). That is, they must completely surround the opening the Multisided Blend will cover.

Constructors

NURBSNBlendSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

There are no additional properties for NURBSNBlendSurface.

Methods

getParent <nurbsnblendsurface> <index>

Returns the NURBSSet index of the indexed curve or surface.

setParent <nurbsnblendsurface> <index> <curve>

Sets the specified parent curve or surface by NURBSSet index as the indexed edge for the surface.

getParentID <nurbsnblendsurface> <index>

Returns the NURBSId of the indexed curve or surface.

setParentID <nurbsnblendsurface> <index> <curveID>

Sets the specified parent curve or surface by NURBSId as the indexed edge for the surface.

getEdge <nurbsnblendsurface> <index>

setEdge <nurbsnblendsurface> <index> <edge>

Get or set which edge of the indexed parent surface is used for the blend. The edge is only applicable if the parent is a surface. the <edge> value is one of the following:

1: The low U edge

2: The high U edge

3: The low V edge

4: The high V edge

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSOffsetSurface : NURBSSurface

This class defines a dependent Offset surface. An Offset surface is offset a specified distance from the original along the parent surface's normals.

Constructors

NURBSOffsetSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsoffsetsurface>.parent : integer

The parent surface by NURBSet index.

<nurbsoffsetsurface>.parentID : integer

The parent surface by NURBSId.

<nurbsoffsetsurface>.distance : float

The distance of the offset surface from the parent surface.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSPointSurface : NURBSSurface

This class defines an independent surface that uses points to describe its shape.

Constructors

NURBSPointSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbspointsurface>.numPoints : point2

The number of points in the point surface in the U and V directions. If this value is changed, the previous point data is not maintained.

<nurbspointsurface>.transform : matrix3

The transformation matrix for the NURBSPointSurface. This controls the relative position of the item within a NURBSSet.

<nurbspointsurface>.closedU : boolean

true if the surface is closed in the U direction, false if open.

<nurbspointsurface>.closedV : boolean

true if the surface is closed in the V direction, false if open.

Methods

closeU <nurbspointsurface>

Close the curve in U.

closeV <nurbspointsurface>

Close the curve in V.

getPoint <nurbspointsurface> <u_index> <v_index>

Get the indexed surface point as a NURBSIndependentPoint; point indexes are 1-based.

setPoint <nurbspointsurface> <u_index> <v_index> <NURBSIndependentPoint>

Get the indexed surface point to the given NURBSIndependentPoint; point indexes are 1-based.

refineU <nurbspointsurface> <v_param>

Add new row of interpolated points in the U direction on the surface at the given parametric V point.

refineV <nurbspointsurface> <u_param>

Add new column of interpolated points in the V direction on the surface at the given parametric U point.

refine <nurbspointsurface> <u_param> <v_param>

Add a new row and column of interpolated points on the surface at the given parametric UV position.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSRuledSurface : NURBSSurface

This class defines a dependent Ruled surface. A Ruled surface is generated from two curve sub-objects. It lets you use curves to design the two opposite borders of a surface.

Constructors

NURBSRuledSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsruledsurface>.parent1 : integer

The 1st parent curve by NURBSet index.

<nurbsruledsurface>.parent1ID : integer

The 1st parent curve by NURBSId.

<nurbsruledsurface>.parent2 : integer

The 2nd parent curve by NURBSet index.

<nurbsruledsurface>.parent2ID : integer

The 2nd parent curve by NURBSId.

<nurbsruledsurface>.flip1 : boolean

Controls the matching of parent curve direction when creating the Ruled surface. For example, normally when you create a Ruled surface between two parent curves you don't want a 'bow tie' surface (one with the ends rotated 180 degrees so it crosses on itself in the middle). If you simply match the parent direction you'll get a 'bow tie' surface. To prevent this you use this property to set a state indicating that one or the other should be flipped before it's used. In this way, when the ruled surface is created, a 'bow tie' won't occur. If true, the 1st parent's curve direction will be flipped; if false the 1st parent's curve direction will not be flipped.

<nurbsruledsurface>.flip2 : boolean

If true, the 2nd parent's curve direction will be flipped; if false the 2nd parent's curve direction will not be flipped.

<nurbsruledsurface>.curveStartPoint1 : float

The start point on the 1st parent curve. This value is only applicable if the curve is closed.

<nurbsruledsurface>.curveStartPoint2 : float

The start point on the 2nd parent curve. This value is only applicable if the curve is closed.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSULoftSurface : NURBSSurface

This class defines a dependent U Loft surface. A U Loft surface interpolates a surface across multiple curve sub-objects. The curves become U-axis contours of the surface.

Constructors

NURBSUloftSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsuloftsurface>.numCurves : integer

The number of curves used by the U Loft.

Methods

getCurve <nurbsuloftsurface> <index>

Gets the NURBSSet index of the indexed U Loft curve; curve indexes are 1-based.

setCurve <nurbsuloftsurface> <index> <curve>

Sets the indexed U Loft curve to the curve specified by the NURBSSet index.

getCurveID <nurbsuloftsurface> <index>

Gets the NURBSId of the indexed U Loft curve in the loft; curve indexes are 1-based.

setCurveByID <nurbsuloftsurface> <index> <curveID>

Sets the indexed U Loft curve to the curve specified by the NURBSId.

appendCurve <nurbsuloftsurface> <curve> [flip:<boolean>] [startPoint:<float>] \

[tension:<float>] [useTangent:<boolean>] [flipTangent:<boolean>]

Adds a curve to the end of the list of U Loft curves by specifying the NURBSSet index. If flip:true is specified, the interpretation of the start and end of the curve to be reversed. startPoint: specifies the start point on the curve. This value is only applicable if the curve is closed. tension: specifies the tension of the curve. If useTangent:true is specified and the curve is a curve on surface, causes the U Loft to use the tangency of the surface. This can help blend a loft smoothly onto a surface. If flipTangent:true is specified, the tangent is flipped for the curve.

appendCurveByID <nurbsuloftsurface> <curveID> [flip:<boolean>] [startPoint:<float>] \

[tension:<float>] [useTangent:<boolean>] [flipTangent:<boolean>]

Adds a curve to the end of the list of U Loft curves by specifying the NURBSId.

getFlip <nurbsuloftsurface> <index>

setFlip <nurbsuloftsurface> <index> <boolean>

Get or set the flip state of the indexed U Loft curve; true causes the interpretation of the start and end of the curve to be reversed, used to control twisting in the loft.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSUVLoftSurface : NURBSSurface

This class defines a dependent UV Loft Surface. This surface is similar to the U Loft surface, but has a set of curves in the V dimension as well as the U dimension.

Constructors

NURBSUVLoftSurface [<property>:<val>]...

any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsuvloftsurface>.numUCurves : integer

The number of curves in the U direction used by the UV Loft.

<nurbsuvloftsurface>.numVCurves : integer

The number of curves in the V direction used by the UV Loft.

Methods

getUCurve <nurbsuvloftsurface> <index>

Gets the NURBSSet index of the U direction indexed UV Loft curve; curve indexes are 1-based.

setUCurve <nurbsuvloftsurface> <index> <curve>

Sets the indexed UV Loft curve in the U direction to the curve specified by the NURBSSet index.

getUCurveID <nurbsuvloftsurface> <index>

Gets the NURBSId of the U direction indexed UV Loft curve in the loft; curve indexes are 1-based.

setUCurveByID <nurbsuvloftsurface> <index> <curveID>

Sets the indexed UV Loft curve in the U direction to the curve specified by the NURBSId.

getVCurve <nurbsuvloftsurface> <index>

Gets the NURBSSet index of the V direction indexed UV Loft curve; curve indexes are 1-based.

setVCurve <nurbsuvloftsurface> <index> <curve>

Sets the indexed UV Loft curve in the V direction to the curve specified by the NURBSSet index.

getVCurveID <nurbsuvloftsurface> <index>

Gets the NURBSId of the V direction indexed UV Loft curve in the loft; curve indexes are 1-based.

setVCurveByID <nurbsuvloftsurface> <index> <curveID>

Sets the indexed UV Loft curve in the V direction to the curve specified by the NURBSId.

appendUCurve <nurbsuvloftsurface> <curve>

Adds a curve to the end of the list of U direction UV Loft curves by specifying the NURBSId.

appendUCurveByID <nurbsuvloftsurface> <curveID>

Adds a curve to the end of the list of U direction UV Loft curves by specifying the NURBSSet index.

appendVCurve <nurbsuvloftsurface> <curve>

Adds a curve to the end of the list of V direction UV Loft curves by specifying the NURBSSet index.

appendVCurveByID <nurbsuvloftsurface> <curveID>

Adds a curve to the end of the list of V direction UV Loft curves by specifying the NURBSId.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSXFormSurface : NURBSSurface

This class defines a dependent Transform (XForm) surface. A Transform surface is a copy of the original surface with a different position, rotation, or scale.

Constructors

NURBSXFormSurface [<property>:<val>]...

any of the object's properties may be set via optional keyword arguments on the constructor.

getObject <nurbsset> <index>

Properties

<nurbsxformsurface>.parent : integer

The parent surface by NURBSet index.

<nurbsxformsurface>.parentID : integer

The parent surface by NURBSId.

<nurbsxformsurface>.transform : matrix3

The offset transformation matrix for the NURBSXFormSurface. This controls the relative position of the item to the parent surface.

See also

NURBSSurface

NURBSObject

Value Common Properties, Operators, and Methods


NURBSTexturePoint : NURBSObject

This class defines a single texture vertex in a NURBS texture surface.

Constructors

NURBSTexturePoint <point2> [indices:<point2>]

Create a NURBSTexturePoint with the specified UV coordinate. If indices: is specified, it sets the ordering the texture point in the texture surface.

getPoint <NURBSTextureSurface> <u_index> <v_index>

Properties

<nurbstexturepoint>.pos : point2

The UV coordinate of the texture point.

Methods

setIndices <nurbstexturepoint> <u_index> <v_index>

Sets the ordering the texture point in the texture surface.

See also

NURBSObject

Value Common Properties, Operators, and Methods


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.

Constructors

NURBSDisplay [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

<nurbsset>.display

Properties

<nurbsdisplay>.displayCurves : boolean

true if curves are displayed; otherwise false.

<nurbsdisplay>.displaySurfaces : boolean

true if surfaces are displayed; otherwise false.

<nurbsdisplay>.displayLattices : boolean

true if lattices are displayed; otherwise false.

<nurbsdisplay>.displaySurfCVLattices : boolean

true if surface CV lattices are displayed; otherwise false.

<nurbsdisplay>.displayCurveCVLattices : boolean

true if curve CV lattices are displayed; otherwise false.

<nurbsdisplay>.displayDependents : boolean

true if dependent sub-objects are displayed; otherwise false.

<nurbsdisplay>.displayTrimming : boolean

true if surface trimming is displayed; otherwise false.

<nurbsdisplay>.degradeOnMove : boolean

true if the surface may degrade while transforming it; otherwise false.

<nurbsdisplay>.displayShadedLattice : boolean

true if the NURBS surfaces appear as shaded lattices in shaded viewports and wireframe viewports display the surface's lattice without shading. false if NURBS surfaces display as tessellated meshes in shaded viewport and wireframe viewports surfaces display as either iso curves or wire meshes.

See also

Value Common Properties, Operators, and Methods


NURBSSelection : Value

An NURBSSelection represents a set of NURBS sub-objects for a scene NURBS node as a virtual array. As such, you can access a sub-object by index, iterate over the sub-objects, and apply mapped functions to the sub-objects. The NURBSSelection array is dynamic, i.e., its contents will change as the sub-objects of the NURBS node change. NURBSSelection values are mappable.

Constructors

<node>.selectedCurveCVs

<node>.selectedCurves

<node>.selectedImports

<node>.selectedPoints

<node>.selectedSurfaces

<node>.selectedSurfCVs

<node>.curveCVs -- read-only

<node>.curves -- read-only

<node>.imports -- read-only

<node>.surfaces -- read-only

<node>.surfCVs -- read-only

<node>.points -- read-only

Properties

<nurbsselection>.count : Integer, read-only

Returns the number of sub-objects in the NURBSSelection array.

<nurbsselection>.selSetNames : Array of names, read-only

Returns an array of names of the current named selection sets corresponding to the NURBSSelection level for the object the NURBSSelection is associated with.

The following property is present for singleton selections (of the form $foo.curveCVs[n]):

<nurbsselection>.index : Integer, read-only

Returns the index of the selected sub-object in the NURBS object, e.g.,

$foo.selectedcurveCVs[2].index

returns the curve CV index of the 2nd curve CV in the current selection.

Note that iterating over a selection yields singleton selections in the loop body:

sCVs = for i in $foo.selectedcurveCVs collect i.index

sCVs contains selected curve CVs as array

Operators

<node>.selectedCurveCVs = (<array> | <bitarray>)

<node>.selectedCurves = (<array> | <bitarray>)

<node>.selectedImports = (<array> | <bitarray>)

<node>.selectedPoints = (<array> | <bitarray>)

<node>.selectedSurfaces = (<array> | <bitarray>)

<node>.selectedSurfCVs = (<array> | <bitarray>)

Selects the specified sub-objects.

<nurbsselection>[<integer>]

Retrieves the indexed sub-object as a singleton NURBSSelection. Index starts at 1

<nurbsselection>[(<integer_array> | <bitarray>)]

Retrieves the indexed sub-objects as a NURBSSelection. Index starts at 1.

<nurbsselection>[(<#name> | <string>)]

Retrieves the sub-object level named selection set, where the name of the named selection set can be specified as a name or string value.

<nurbsselection>[(<#name> | <string>)] = (<nurbsselection> | <integer_array> | <bitarray>)

Sets the sub-object level named selection set to the specified edges. The name of the named selection set can be specified as a name or string value, and the edges can be specified as an array, bitArray, or a NURBSSelection from the same object and of the same sub-object level.

Methods

move <nurbsselection> <point3>

Moves the sub-objects in the NURBSSelection.

rotate <nurbsselection> <quat_or_other_rotation_form>

Rotates the sub-objects in the NURBSSelection.

scale <nurbsselection> <point3>

Scales the sub-objects in the NURBSSelection.

select <nurbsselection>

Selects the sub-objects in the NURBSSelection.

deselect <nurbsselection>

Deselects the sub-objects in the NURBSSelection.

delete <nurbsselection>

Deletes the sub-objects in the NURBSSelection.

append <nurbsselection> (<nurbsselection> | <integer>)

Appends the sub-objects(s) to the NURBSSelection.

findItem <nurbsselection> (<nurbsselection[<integer>] | <integer>)

Returns the selection index of the matching item or 0 if not found. The item is selection index or singleton NURBSSelection.

Examples

$foo.surfCVs[#baz] -- retrieves the surf CV selection named baz

move $foo.curves[#bar] [0,0,10] -- moves the "bar" curve selection 10 in Z

move $foo.selectedSurfCVs [0,0,10] -- moves the current surface CV selection 10 in Z

coordsys local scale $foo.surfaces[#baz] [2,2,2]

select $foo.curveCVs[#(1,2,3,4,5)] -- select the specified curve CVs

deselect $foo.curves -- deselect all curves

delete $foo.points[#{1..31, 40..50}] -- delete the specified points

$foo.curveCVs[#fred] = $foo.selectedCurveCVs - "snapshot" the selected curve CVs

See also

Value Common Properties, Operators, and Methods


NURBSSet : Value

This is the class used to create NURBS objects, or retrieve data from existing NURBS objects. The NURBSSet acts as a container for the other objects.

This class contains a table of the various NURBSObject derived entities (points, curves, surfaces) used to make up the set. Additionally it has two 'fuse' tables: one for fuse curves and one for fuse surfaces. These are used to allow the CVs in the curves or surfaces to be 'stitched' or 'fused' together so that if one curve or surface moves the other moves with it. This class also has the surface-approximation properties that control the object's tessellation into triangle meshes for use in the viewports and the production renderer.

NURBSSet values are mappable.

Constructors

NURBSSet [<property>:<val>]...

any of the object's properties may be set via optional keyword arguments on the constructor

getNURBSSet <node> [#relational]

This function is used to retrieve a NURBSSet that corresponds to the specified NURBS scene node. This allows access the internal objects inside a 3ds max editable NURBS object.

If the optional #relational parameter is not supplied, the returned NURBSSet will contain only independent curves and surfaces, all dependent objects will be decomposed into corresponding independent objects. So for example, if you pass an object that has a relational model (perhaps two CV surfaces and a dependent blend surface) it will decompose them into three CV surfaces. This will be the CV surfaces that represent the two surfaces and the blend, but you won't have the blend relational data. If the #relational argument is supplied, you get back two CV surfaces and a NURBS blend surface and the NURBSSet is an active representative for the scene object -- any changes you make to the properties of it's constituent NURBSObjects will be reflected directly in the source scene object.

Properties

<nurbsset>.numObjects : integer, read-only

<nurbsset>.count : integer, read-only

The number of internal objects in the NURBSSet.

The following properties control the surface approximation tessellation. There are dual sets of properties, one for controlling viewport tessellation, the other for controlling renderer tessellation. The properties correspond directly to the surface approximation controls in the NURBS surface modifier panel. See NURBSSurfaceApproximation for a description of these properties.

<nurbsset>.viewConfig : #isoOnly, #isoAndMesh, #meshOnly

<nurbsset>.viewIsoULines : integer

<nurbsset>.viewIsoVLines : integer

<nurbsset>.viewMeshUSteps : integer

<nurbsset>.viewMeshVSteps : integer

<nurbsset>.viewMeshApproxType : #parametric, #spatial, #curvature,

: #regular, #spatialAndCurvature

<nurbsset>.viewSpacialEdge : float

<nurbsset>.viewCurvatureAngle : float

<nurbsset>.viewCurvatureDistance : float

<nurbsset>.viewViewDependent : boolean

<nurbsset>.renderConfig : #isoOnly, #isoAndMesh, #meshOnly,

: #regular, #spatialAndCurvature

<nurbsset>.renderIsoULines : integer

<nurbsset>.renderIsoVLines : integer

<nurbsset>.renderMeshUSteps : integer

<nurbsset>.renderMeshVSteps : integer

<nurbsset>.renderMeshApproxType : #parametric, #spatial, #curvature,

: #regular, #spatialAndCurvature

<nurbsset>.renderSpacialEdge : float

<nurbsset>.renderCurvatureAngle : float

<nurbsset>.renderCurvatureDistance : float

<nurbsset>.renderViewDependent : boolean

<nurbsset>.display : NURBSDisplay

Takes and returns instances of the NURBSDisplay class that controls visibility of various components of a NURBS object's display in the viewports.

<nurbsset>.viewApproximation : NURBSSurfaceApproximation

<nurbsset>.renderApproximation : NURBSSurfaceApproximation

These properties are used to access and control surface approximation using the NURBSSurfaceApproximation class, instances of which encapsulate all the approximation settings for either viewports or rendering. You can construct a surface approximation setup in one of these instances and use it to set the surface approximation for many objects.

<nurbsset>.merge : float

Controls the tessellation of surface sub-objects whose edges are joined or very nearly joined. When input to a modifier as Mesh Select which requires a mesh, and when NURBS surfaces are tessellated for production rendering, by default 3ds max adjusts the tessellation of adjoining surfaces to match each other in terms of the number of faces along the edges. The merge value controls how this is done. If merge is zero, adjoining faces are unchanged. Increasing the value of merge increases the distance 3ds max uses to calculate how edges should match, guaranteeing no gaps between the surfaces when they are rendered.

Operators

<nurbsset>[<index>]

<nurbsset>[<index>] = <nurbsobj>

The sub-objects in a NURBSSet can be accessed using the standard MAXScript array indexing operator, []. This is equivalent to using the getObject() and setObject() methods described below.

Methods

appendObject <nurbsset> <nurbsobj>

Appends the given NURBSObject (instances of any of the subclasses of NURBSObject and their subclasses, all the points, curves, surfaces) as a new sub-object to the NURBSSet. The new sub-object receives the next available index.

setObject <nurbsset> <index> <nurbsobj>

Set the indexed sub-object to the given NURBSObject; indexes are 1-based. You use this function to replace a previously appended object.

getObject <nurbsset> (<index> | <NURBSSelection>)

Retrieves the indexed sub-object or the set of sub-objects specified by the NURBSSelection from the NURBSSet; sub-object indexes are 1-based. If the NURBSSelection specifies no sub-objects, undefined is returned. If one sub-object is specified, a value of that sub-object's class is returned. If multiple sub-objects are specified, a NURBSSet value is returned.

removeObject <nurbsset> <index>

Removes the given sub-object from the NURBSSet. The indexes of all the remaining higher-indexed sub-objects are renumbered down.

disconnect <nurbsset>

Disconnect a relational NURBS set from its scene object, turning it into a non-relational set.

deleteObjects <nurbsset>

This method deletes all the NURBSObjects in a NURBSSet, and frees its memory.

getProdTess <nurbsset> <tessType_name>

setProdTess <nurbsset> <tessType_name> <NURBSSurfaceApproximation>

getViewTess <nurbsset> <tessType_name>

setViewTess <nurbsset> <tessType_name> <NURBSSurfaceApproximation>

These methods get and set renderer and viewport NURBSSurfaceApproximation values for individual surfaces, where <tessType_name> is one of #surface, #displacement, or #curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.

clearProdTess <nurbsset> <tessType_name>

clearViewTess <nurbsset> <tessType_name>

Resets the surface approximation settings for the surfaces in the NURBSet for the given tessellation type, where <tessType_name> is one of #surface, #displacement, or #curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.

See also

Value Common Properties, Operators, and Methods


NURBSSurfaceApproximation : Value

Instances of this class contain a complete surface approximation setting that can be used to set the approximation for NURBS objects described by NURBSSet values or directly in existing NURBS scene node. You use the setViewApproximation() and setRenderApproximation() functions on existing scene nodes and the .viewApproximation and .renderApproximation properties on NURBSSet values.

Constructors

NURBSSurfaceApproximation [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

<nurbsset>.viewApproximation

<nurbsset>.renderApproximation

Properties

<nurbssurfaceapproximation>.config : #isoOnly, #isoAndMesh, #meshOnly

This property determines what is displayed in the interactive or scanline renderer.

If #isoOnly is specified, only Iso lines are displayed. Iso (parametric) lines are similar to contour lines. The lines show where the NURBS surface has a constant U or V value or both. Iso line representations can be less crowded and easier to visualize than wire mesh representations.

If #isoAndMesh is specified, Iso lines and the mesh are displayed. When chosen, wireframe viewports display iso line representations of the surface, and shaded viewports display the shaded surface.

If #meshOnly is specified, just the mesh is displayed. When chosen, wireframe viewports display the surface as a wire mesh, and shaded viewports display the shaded surface. In wireframe viewports, this option lets you see the curve approximation used for viewports.

<nurbssurfaceapproximation>.isoULines : integer

This is used with the ISO line display. This is the number of additional interior iso lines in U (there are always lines along the outer edges).

<nurbssurfaceapproximation>.isoVLines : integer

This is used with the ISO line display. This is the number of additional interior iso lines in V (there are always lines along the outer edges).

<nurbssurfaceapproximation>.meshUSteps : integer

This is used for parametric tessellation. This is the number of tessellations in U. This is the number of sub-divisions for a knot span for the surface.

<nurbssurfaceapproximation>.meshVSteps : integer

This is used for parametric tessellation. This is the number of tessellations in V. This is the number of sub-divisions for a knot span for the surface.

<nurbssurfaceapproximation>.meshApproxType : #parametric, #spatial, #curvature,

: #regular, #spatialAndCurvature

This property controls the type of surface tessellation.

If #parametric is specified, parametric tessellation is performed. This provides for a fixed number of meshUSteps by meshVSteps tessellations. There are meshUSteps times meshVSteps quadrilaterals and each one is split up into two triangles.

If #spatial is specified, spatial tessellation is performed. This uses spacialEdge as its parameter. This specifies that the size of the tessellation will be the spacialEdge length. In view dependent tessellation spacialEdge is specified in pixels.

If #curvature is specified, view dependent tessellation is performed. This uses the curvatureAngle and curvatureDistance property values.

If #regular is specified, a fixed, regular tessellation across the surface is performed.

If #spatialAndCurvature is specified, a tessellation method which combines the spatial and curvature methods is used. This uses the spacialEdge, curvatureAngle, and curvatureDistance property values.

<nurbssurfaceapproximation>.spacialEdge : float

This is the length of an edge to use in spatial (#spatial) tessellation. In view dependent tessellation this is specified in pixels. If not in view dependent tessellation this is a percentage of the bounding box diagonal length.

<nurbssurfaceapproximation>.curvatureAngle : float

This is used in curvature dependent tessellation (#curvature). If 0.0 is specified this is ignored. If specified this ensures that no two adjacent face normals exceed this angle between them. This value is specified in radians.

<nurbssurfaceapproximation>.curvatureDistance : float

This is used in curvature dependent tessellation (#curvature). If 0.0 is specified this is ignored. This specifies a distance that cannot be exceeded between a vertex on the mesh and the mathematical surface. This is defined as a percentage of the diagonal of the bounding box of the individual surface in object space. For instance if this was set to 1.0, the allowable error in generating a tessellation would be 1% of the bounding box diagonal distance of the surface. This would be 1/100 (1%) of the diagonal distance of the bounding box. In this way if an object is scaled the tessellation remains the same. Additionally, if you have an object with a big surface and a little surface, the smaller surface will get tessellated more finely because its own bounding box is used. This prevents the smaller surface from just becoming a single triangle for example.

<nurbssurfaceapproximation>.viewDependent : boolean

Specifies if this is view dependent tessellation. If true this will tessellate less finely the farther away from the camera the object is. If false the tessellation does not change based on distance from the camera.

See also

Value Common Properties, Operators, and Methods


NURBSTextureSurface : Value

This class contains an editable texture coordinate surface corresponding to the editable texture surface in NURBS surfaces. You can create and apply them to any NURBSSurface value or retrieve existing texture surfaces using the getTextureSurface() and setTextureSurface() methods to access any of the 99 texture channels for a NURBS surface.

3ds max uses the texture surface to control how materials are mapped. In effect, changing the texture surface stretches or otherwise changes the UV coordinates for the surface, altering the mapping. This is a 2D (not 3D) surface that lives in the parameter space of the corresponding NURBSSurface which controls the texture mapping used by the NURBSSurface.

It is not possible to assign texture surfaces to NURBS objects that are present in the scene. You can create new NURBSSets and the texture surface is used when you call createNURBSObject(). However, if you do a getNURBSSet() and assign a NURBSTextureSurface to a texture channel for a NURBS surface, nothing happens.

Constructors

NURBSTextureSurface [<property>:<val>]...

Any of the object's properties may be set via optional keyword arguments on the constructor.

getTextureSurface <nurbssurface> <channel_index>

<nurbssurface>.textureSurface1

<nurbssurface>.textureSurface2

Provides backward compatibility for scripts written for 3ds max R2.5. Get and set the texture surfaces for the first two texture channels.

Properties

<nurbstexturesurface>.type : #default, #userDefined, #projected

The type of texture surface.

<nurbstexturesurface>.parent : integer

The parent surface by NURBSet index.

<nurbstexturesurface>.parentID : integer

The parent surface by NURBSId.

<nurbstexturesurface>.numUPoints : integer -- read-only

<nurbstexturesurface>.numVPoints : integer -- read-only

<nurbstexturesurface>.numPoints : point2

The number of U and V points.

Methods

getPoint <nurbstexturesurface> <u_index> <v_index>

setPoint <nurbstexturesurface> <u_index> <v_index> <texturepoint>

Get or set a NURBSTexturePoint value for the texture point at the U and V index of the texture surface.

Associated Methods

setTextureSurface <nurbssurface> <channel_index> <NURBSTextureSurface>

This method sets the texture surface for the selected channel.

Notes

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

Value Common Properties, Operators, and Methods


Biped and Physique

The following topics describe the MAXScript access to Biped systems and the Physique modifier:

Biped : System

Physique : Modifier

Biped-Related Classes

PhyContextExport Values

PhyRigidVertex Values

PhyBlendingRigidVertex Values

BipedExportInterface Values

The following is an example of accessing Physique data:

Example:

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.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


BipedExportInterface Values

The BipedExportInterface class is an interface into a Biped.

Constructor

getBipedExportInterface <biped_node>

Returns an instance of BipedExportInterface class. The biped_node can be any node associated with the Biped system, including the footprints.

Methods

setNonUniformScale <BipedExportInterface> <boolean>

Biped-based bone systems created prior to Character Studio version R2.1 have non-uniform scaling on the nodes that make up the biped object. This scaling can cause difficulties when exporting the biped. This function removes or restores the non-uniform scaling on a biped object. If <boolean> is true the non-uniform scaling will be set, and false will remove it. All non-uniform scaling information has been removed from new bipeds created with version R2.1 or greater of Character Studio, and this method is not required for exporting these bipeds.


Physique : Modifier

Constructor

physique ...

Properties

There are no properties associated with Physique.

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


PhyContextExport Values

The PhyContextExport class is an interface into the physique vertex data. It can be used to retrieve vertex data of the modifier. Currently it only supports rigid vertices (blended and non-blended). You can use convertToRigid() to convert all vertices into rigid.

Constructor

getPhyContextExport <node> <physique_modifier>

Returns an instance of PhyContextExport class.

Properties

<GetPhyContextExport>.numVerts

Returns the number vertices in the object. This property is read-only.

Methods

convertToRigid <PhyContextExport> <boolean>

Converts all vertices into rigid vertices. If a true value is passed then getVertexInterface() converts a deformable vertex into a rigid vertex and returns the vertex. If a false value is passed then getVertexInterface() returns undefined for a deformable vertex.

allowBlending <PhyContextExport> <boolean>

If a true value is passed then getVertexInterface() returns a PhyBlendingRigidVertex, if a vertex is blended, otherwise undefined.

getVertexInterface <PhyContextExport> <index_integer>

Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or PhyBlendingRigidVertex.

See also

PhyRigidVertex Values

PhyBlendingRigidVertex Values


PhyRigidVertex Values

The PhyRigidVertex class representing a rigid vertex in a Physique modifier. A rigid vertex can be linked to only one node.

Constructor

getVertexInterface <PhyContextExport> <index_integer>

Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or PhyBlendingRigidVertex.

Methods

getNode <PhyRigidVertex>

Returns the node the vertex is linked to.

getOffsetVector <PhyRigidVertex>

Returns the coordinates of the vertex in the local coordinates of associated node.


PhyBlendingRigidVertex Values

The PhyBlendingRigidVertex class representing a blended vertex in a Physique modifier. A blended vertex can be linked to multiple nodes.

Constructor

getVertexInterface <PhyContextExport> <index_integer>

Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or PhyBlendingRigidVertex.

Properties

<PhyBlendingRigidVertex>.numNodes

Returns the number of nodes the vertex is linked to. This property is read-only.

Methods

getNode <PhyBlendingRigidVertex> <index_integer>

Returns the indexed node the vertex is linked to.

getOffsetVector <PhyBlendingRigidVertex> <index_integer>

Returns the coordinates of the vertex in the local coordinates of indexed node.

getWeight <PhyBlendingRigidVertex> <index_integer>

Returns the weight of the indexed node on the vertex.


Missing Object Classes

The following classes are used to represent objects in the scene for which the plug-in defining the object class is missing. An example of this is if you load a scene containing a Biped, but you do not have the Character Studio plugins, the biped objects will be retained in the scene, and the object's class will be shown as the appropriate missing object class. These classes are not creatable by MAXScript and do not have any properties or methods.

Missing_Atmospheric

Standin for missing Atmospheric class objects.

Missing_Camera

Standin for missing Camera class objects.

Missing_Float_Control

Standin for missing Float controller class objects.

Missing_GeomObject

Standin for missing Geometry object class objects.

Missing_Helper

Standin for missing Helper object class objects.

Missing_Light

Standin for missing Light object class objects.

Missing_Matrix3_Control

Standin for missing Matrix3 controller class objects.

Missing_Morph_Control

Standin for missing Morph controller class objects.

Missing_Mtl

Standin for missing Material class objects.

Missing_OSM

Standin for missing Object Space Modifier class objects.

Missing_Point3_Control

Standin for missing Point3 controller class objects.

Missing_Position_Control

Standin for missing Position controller class objects.

Missing_RefTarget

Standin for missing Reference Target class objects.

Missing_Render_Effect

Standin for missing Render Effect class objects.

Missing_Rotation_Control

Standin for missing Rotation controller class objects.

Missing_Scale_Control

Standin for missing Scale controller class objects.

Missing_Shape

Standin for missing Shape class objects.

Missing_System

Standin for missing System class objects.

Missing_TextureMap

Standin for missing TextureMap class objects.

Missing_UVGen

Standin for missing UVGen class objects.

Missing_WSM

Standin for missing World Space Modifier class objects.

Missing_WSM_Object

Standin for missing World Space Modifier Object class objects.

Missing_XYZGen

Standin for missing XYZGen class objects.


Scripting Vertex and Control Point Animation

You can add animation to vertices in editable meshes, spline shapes and FFD modifiers using the animateVertex() method. Its syntax is:

animateVertex <node_or_ffd_modifier> <vertex_spec>

Animates one or more vertex, knot, or control point, where <vertex_spec> is one of

<index>

<index_array>

#all

#selected -- not applicable for FFD modifiers

For FFD modifiers, the animateAll() method will animate all the control points, and is equivalent to animateVertex <ffd_modifier> #all. Its syntax is:

animateAll <ffd_modifier>

Animates all control points.

The animateVertex() and animateAll() methods effectively assign controllers to editable meshes, spline shapes and FFD modifiers which make them appear as animatables in the Track View, allowing further scripting of these vertex animation controllers.

Examples:

animateVertex $line01 2

animateVertex $box01 #(2,3,4,5)

animateAll $box01.ffd_3x3x3

These animateVertex() method only work on editable meshes, spline shapes and FFD modifiers and will report an error if applied to other types of objects. You can use the functions convertToMesh() and convertToSplineShape() to convert existing geometry into the needed forms. Note that Line objects are SplineShapes already and don't need conversion.

The vertices to be animated are specified by index number, with the keyword #all to animate all vertices or control points, or #selected to animate the currently selected vertices. The #selected keyword is not applicable to FFD modifiers. In the case of SplineShapes, the vertex index numbers are interpreted in a special way to accommodate tangent handles and multiple curves, as follows:

  • Each SplineShape vertex has three indexes, one for each in-tangent handle, vertex, and out-tangent handle, in that order.

  • The indexes run consecutively through each curve in a multi-curve shape, with the index number for the first in-tangent handle of a curve starting after the index of the last out-tangent handle in the prior curve.

See also Class and Object Inspector Functions 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 Modifier Common Properties, Operators, and Methods.

For editable meshes and spline shapes, the controller values assigned to the vertices, knots, and tangent handles is in object space. See Using Node Transform Properties for information on converting between world space to object space.


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

Utility Clauses

Managing Multiple Rollouts in a Scripted Utility

Rollout Clauses

Utility and Rollout Properties, Methods, and Event Handlers

Rollout User-Interface Controls

Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code

Accessing Locals and Other Items in a Rollout from External Code

Rollout Floater Windows


Scripted Utility Panels

A scripted utility panel is created using the utility definition construct in MAXScript. The top-level syntax is as follows:

utility <var_name> <description_string>

[ rolledUp:<boolean> ] [ silentErrors:<boolean> ]

( <utility_body> )

The <var_name> is the name of an automatically created global variable to hold the value that represents the scripted utility panel.

The <description_string> is a string which is used as the description for the utility in the Utilities list in the MAXScript rollout.

The optional rolledUp: parameter specifies whether the utility rollout is initially rolled up. If set to true, the utility rollout is initially rolled up. The default value is false.

The optional silentErrors: parameter controls whether MAXScript runtime error messages are displayed while executing the scripted utility. If this parameter is set to false, error messages are displayed to Listener and possibly to a pop-up error dialog, and continued execution of the utility is terminated. If this parameter is set to true, error messages will not be displayed, and continued execution of the utility is permitted. Setting this parameter to true is useful for distributed scripted plug-ins that may confuse the user with MAXScript error messages. The default value is false.

The <utility_body> is inside the required parentheses and is a sequence of clauses that defines the user-interface items that will appear in the utility, along with functions and event handlers that process user interactions, as defined in detail in Utility Clauses.

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.

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.


Utility Clauses

The <utility_body> of a scripted utility definition is composed of a sequence of utility clauses as follows:

<utility_body> ::= { <utility_clause> }+

where

<utility_clause> ::= <rollout_clause> | <nested_rollout>

A <utility_clause> can contain one or more instances of <rollout_clause> or <nested_rollout>. A nested rollout is basically another self-contained rollout definition which can be used to construct scripted utilities with multiple rollouts or populate rollout floater windows that may be associated with the utility. A <nested_rollout> is defined as follows:

rollout <var_name> <description_string>

[ rolledUp:<boolean> ] [ silentErrors:<boolean> ]

( <rollout_body> )

where

<rollout_body> ::= { <utility_clause> }+

In other words, a rollout definition is identical to a utility definition except its description string is not displayed in the Utilities list in the MAXScript rollout. In fact, a utility can just be considered a special case of a rollout, and both are instances of the Rollout class.

As an example, consider the following script. In this script, line 1 defines the start of the utility, and the utility body is lines 2 through 42. The following line ranges are utility clauses: 3 (a rollout clause), 5 to 9 (a nested rollout), 11 to 30 (a nested rollout), 32 to 35 (a rollout clause), and 37 to 40 (a rollout clause).

Script:

utility MyUtil "My Utility"

(

local pot

rollout bout "About My Utility"

(

button aboutMU "About" width:45 height:20

on aboutMU pressed do

messagebox "My First Utility\nby ME\nVersion .1" \

title:"About My Utility"

)--end rollout bout

rollout creator "The Teapot"

(

group "Object Creator"

(

button tea "Teapot"

spinner rad "Radius" range:[10,50,20] type:#integer

spinner seg "Segments" range:[4,32,12] type:#integer scale:1

)

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 Rollout Floater Windows.

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 Scope of Variables.


Managing Multiple Rollouts in a Scripted Utility

MAXScript includes support for managing multiple rollouts in one utility, which is useful in large scripted utilities that would be unwieldy in one rollout. There is one main rollout defined by the user-interface items in the utility definition itself. The other rollouts are defined as nested rollouts within the body of the utility definition. These other rollouts can be added to and removed from the Utilities panel under script control.

You define extra rollouts with the rollout clause inside a utility definition:

utility foo "name"

(

local ...

spinner ...

...

rollout baz "name"

(

local ...

checkbox ..

on ...

)

...

)

Such nested rollouts can contain anything a utility definition can contain with the exception of further nested rollouts. Nested rollouts are not automatically opened or closed when the parent utility rollout opens and closes. You need to explicitly do this in the open and close handlers or other handlers or functions in the utility. There are two new functions for this:

addRollout <rollout> [ rolledUp:<boolean> ]

removeRollout <rollout>

The rolledUp: parameter on the addRollout() function specifies whether the rollout is added in a rolled-up state. This defaults to false, so the rollout is added fully opened. The nested rollouts are arranged in the order of addRollout() calls, so take care in sequencing these to ensure the order you want.

The nested rollouts do not automatically get removed when the main utility rollout is closed. You must make sure they are explicitly removed, typically in the close handler for the main utility.

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


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 Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code and Accessing Locals and Other Items in a Rollout from External Code.

  • Mouse tools are used to perform a set of actions based on mouse clicks in the 3ds max viewports, and are described in Scripted Mouse Tools.

  • User-interface control items are elements displayed in the rollout, such as buttons, spinners, and list boxes.

  • Event handlers are special kinds of functions associated with particular user-interface control items. Event handlers specify the processing you want to occur when a user interacts with a user-interface item. For example pressing a button or adjusting a spinner. These user actions generate named events and the optional event handler you supply for that event is called when the user action occurs. For example, if you press a button named DoIt, the on DoIt pressed event handler expression is executed.

Formally, the syntax of a <rollout_clause> is defined as follows:

<rollout_clause> ::= <local_variable_decl> |

<local_function_decl> |

<local_struct_decl> |

<global_variable_decl>|

<mousetool> |

<user_interface_item> |

<item_group> |

<event_handler>

Locals

A <local_variable_decl>, <global_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly the same as local and global variable, local function, and local structure definitions in MAXScript:

<local_variable_decl> ::= local <decl> { , <decl> }

<decl> ::= <name> [ = <expr> ] -- optional initial value

<global_variable_decl>::= global <decl> { , <decl> }

<decl> ::= <name> [ = <expr> ] – optional initial value

<local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr>

<local_struct_decl> ::= struct <name> ( <member> { , <member> } )

<member> ::= ( <name> [ = <expr> ] | <local_function_decl> )

Examples of the previous (in order) are:

local numSelected

global foo

local numSelected = 0

fn onlyOneSelected = (selection.count == 1)

struct parents (mother="", father="")

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 Scope of Variables.

User-Interface Items

A <user_interface_item> defines an individual button, check box, spinner, or other user-interface control item that will appear in the rollout. These user-interface control items are described in Rollout User-Interface Controls.

An <item_group> is used to place a sequence of user-interface items in a labeled box in the rollout, so you can organize large rollouts into meaningful groups. Its syntax is:

group <group_label_string> ( { <user_interface_item> } )

The use of group is shown in the following script:

Utility Infinity "Game Utilities"

(

group "Lighting"

(

label label1d "Number of Day lights:" across:2 offset:[10,0]

label label2d "0" offset:[10,0]

label label1n "Number of Night lights:" across:2 offset:[13,0]

label label2n "0" offset:[10,0]

label label3

Radiobuttons WhichOn "Active Lights:" labels:#("Day","Night")

)

group "Scene Data Dump"

(

Button scenedump "Dump Scene Data"

)

group "Exclusions/Inclusions"

(

Button DispExcl "Unhide Exclusions&Inclusions"

)

group "Camera Mattes"

(

radiobuttons CamMatte labels:#("None","1","2","3","4") columns:3

)

Button resetb "Reset"

)

The Utilities panel rollout which the previous script generates looks like the following figure.

Game Utilities rollout using group user-interface item

Event Handlers

An <event_handler> is a special function definition local to a utility or rollout that you provide to handle the processing you want to occur when a user performs an action on a user-interface item. For example, event handlers are called when the user presses a button or adjusts a spinner, opens or closes the utility or rollout, or resizes or moves a rollout floater window. These user actions generate named events and any event handler you supply for that event is called when the action occurs. The syntax for defining an event handler is as follows:

on <item_name> <event_name> [ <argument> ] do <expr>

The <item_name> specifies the name of the item to which this handler is connected. The <event_name> specifies the type of event to be handled and the optional <argument> is used to pass various values to the handler. The possible events you can specify depend on the item type. These events include:

pressed

changed

picked

entered

selected

resized

moved

open

close

The available events and the arguments passed are defined in the description for each user-interface item type, as listed in Rollout User-Interface Controls. The available events and the arguments passed for utilities and rollouts are described in Utility and Rollout Properties, Methods, and Event Handlers.

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.


Utility and Rollout Properties, Methods, and Event Handlers

Properties

Several properties are available for scripted utilities and rollouts which provide control over whether a rollout is open and the rollout scroll state. These properties are:

<rollout_or_utility>.open Boolean

Indicates whether the rollout is in an open or rolled-up state. If true, the rollout is open, false it is rolled up. You can assign true or false to this property to open or roll up the rollout.

<rollout_or_utility>.scrollPos Integer

This property is, strictly speaking, a property of the entire collection of rollouts in a rollout floater window or the Utilities panel, and gives the scroll position for the rollout set when opened in a panel that is too small to show all the rollouts. It can be accessed as a property on any rollout currently present in a rollout floater window or the Utilities panel.

You can implement a form of rollout state save and restore for your scripted rollouts by recording the open state of all rollouts and the scrollPos of the entire panel during close handler processing, and then reset the values in the open handler.

Methods

Several methods are available for opening and closing utilities, and adding and removing rollouts in the Utilities panel. These methods are:

openUtility <utility>

Opens the utility's main rollout in the Utilities panel. This is equivalent to selecting the utility from the Utilities list in MAXScript's Utilities panel rollout.

closeUtility <utility>

Closes the utility's main rollout in the Utilities panel. This is equivalent to clicking the Close button in this rollout.

addRollout <rollout> [ rolledUp:<boolean> ]

Adds the rollout to the Utilities panel. The rolledUp: parameter on the addRollout() function specifies whether the rollout is added in a rolled-up state. This defaults to false, so the rollout is added fully opened. The extra rollouts are arranged in the order of addRollout() calls, so take care in sequencing these to ensure the order you want.

removeRollout <rollout>

Removes the rollout from the Utilities panel.

See Managing Multiple Rollouts in a Scripted Utility for more information on the addRollout() and removeRollout() methods.

Event Handlers

In addition to the event handlers you specify for particular user-interface items in a rollout, you can define handler functions that are called when an entire rollout is first opened (open) or explicitly closed (close) by the user. These event handlers are useful for initialization code or for cleaning up when a rollout closes, and are necessary when managing multiple rollouts in one scripted utility. If a rollout floater window is resized or moved, an event handler (resized or moved, respectively) is called on the first rollout in the rollout floater window. An additional event handler (oktoclose) is called to verify that it is OK to close a rollout. The syntax is as follows:

on <rollout_or_utility> open do <expr>

Called when the rollout or utility is opened.

on <rollout_or_utility> close do <expr>

Called when the rollout or utility is closed.

on <rollout_or_utility> oktoclose do <expr>

Called when the user clicks the rollout's Close button so the script writer can decide whether to allow the close to proceed. If the expression evaluates to the value true, the rollout is allowed to close. If the expression evaluates to the value false, the action attempting the close is ignored and the rollout or utility is left open.

on <rollout> resized <arg> do <expr>

Called on first rollout in a rollout floater window when it is resized either by the user or by a script changing the size property of the rollout floater window. Changing the rollout floater window size in the resized event handler expression will not cause the resized event handler to be called again. The value of <arg> is the current width and height of the rollout floater window. For example:

global my_rof_size

...

on my_rollout resized size do

(

my_rof_size = size -- save the new window size

)

on <rollout> moved <arg> do <expr>

Called on first rollout in a rollout floater window when it is moved either by the user or by a script changing the pos property of the rollout floater window. The value of <arg> is the current position of the rollout floater window on the screen in pixels.

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:

Example:

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.

Example:

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

MAXScript lets you create modeless dialog windows and populate them with rollouts defined using global rollout definitions or utility rollout definitions. The user can resize a rollout floater window vertically by dragging on the lower window edge.

There are two functions and a special class in support of this, as follows:

newRolloutFloater <title_string> <width_integer> <height_integer> \

[<top_integer> <left_integer>]

Creates and opens a new rollout floater window with the title and width and height given. If you don't supply top and left coordinates, the window will open centered in the screen. The width of the 3ds max command panel is 218, in case you want to duplicate its width for precisely accommodating Utilities panel rollouts.

This method returns a RolloutFloater value to which you add rollouts.

closeRolloutFloater <rolloutFloater>

Closes the rollout floater window. The user can also do this by clicking the close box on the window. Once closed, the window is no longer usable. All the close handlers in the rollout floater window's rollouts are called and they are released for use in other rollout floater windows or scripted utilities.

The existing functions for adding and removing rollouts to the Utilities panel are extended to work with rollout floater windows:

addRollout <rollout> [ <rolloutFloater> ] [ rolledUp:<boolean> ]

If the optional second argument is specified, it must be a RolloutFloater value as returned from the newRolloutFloater() function. The rollout specified by the first argument is appended after any rollouts previously in the window.

removeRollout <rollout> [ <rolloutFloater> ]

Removes the rollout from the given rollout floater window.

In both functions above, if the optional <rolloutFloater> is not supplied the rollout is added to, or removed from, the Utilities panel, as described in Managing Multiple Rollouts in a Scripted Utility.

Rollout floater windows have the following properties:

<rolloutFloater>.size Point2

The current size of the rollout floater window in pixels. The first component of the Point2 is the width, the second the height. This property is read/write.

<rolloutFloater>.pos Point2

The current screen position of the rollout floater window in pixels. This property is read/write.

When a rollout floater window is resized, either by the user or by a script changing the size property, a resized event is generated for the first rollout in the rollout floater window. Likewise, when a rollout floater window is moved, either by the user or by a script changing the pos property, a moved event is generated for the first rollout in the rollout floater window. The event handler for the resized and moved events are described in Utility and Rollout properties, Methods, and Event Handlers.

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:

utility foo "name"

(

local ro1, ro2, ... -- declare local rollouts

...

rollout ro1 "name"

(

local ...

checkbox enable ...

on ... do

ro2.enable.checked = false

)

...

rollout ro2 "name1"

(

local ...

checkbox enable ...

on ... do

ro1.enable.checked = true

)

...

)

As a general rule, it is recommended that all local variable names be explicitly declared as locals at their outermost scope. This will prevent any conflicts from occurring if another script has declared the same variable name as a global variable. While functions, structures definitions, and rollouts will always be local to the utility they are defined in (even if they have the same name as a global variable), declaring these as local will ensure the variables are defined, even if the order in which they are defined is changed. Here's an example showing these declarations:

utility foo "Object Frabulator"

(

-- local variables

local target_obj

-- local functions

local prop_name

-- local rollouts

local setup

fn prop_name obj name =

for c in obj.children do c.name = name + "_" + c.name

checkbutton setup_btn "Setup"

edittext name_box "New name:"

-- use a checkbutton to dynamically control presence of panels

on setup_btn changed state do

if state then addRollout setup else removeRollout setup

on foo close do

removeRollout setup -- always close rollouts

rollout setup "Setup fraber" -- local panel

(

label hello

pickbutton pick_tgt "Pick object"

on pick_tgt picked obj do

(

target_obj = obj -- access utility local

name_box.text = obj.name -- access utility item

prop_name obj obj.name -- call utility local fn

)

)

)


Accessing Locals and Other Items in a Rollout from External Code

The local components defined in a scripted utility or rollout are accessible to external code as properties of the utility or rollout object. Recall that the rollout object is assigned to a new global variable (or local variable if a nested rollout) named on the utility or rollout definition.

Example:

utility foo "Object Frabulator"

(

local var1, var2, ...

...

checkbox enable "Enable frabber"

...

rollout setup "Setup frabber" -- local panel

(

local var3

button doit "Execute"

...

on doit pressed do ...

)

function frab a b = ...

...

on enable changed state do ...

...

)

The example defines the utility and places the utility object in a global variable named foo. You can access components in the utility from the Listener or other code as properties of that object, using the name of the variable or item as the property name. Any event-handler functions supplied for user-interface items can also be accessed as sub-properties of the item, using the event name as the property name. For example:

print foo.var1 -- get foo's local variable, var1

if foo.enable then ... -- test foo's enabled checkbox

foo.enable = false -- set it

foo.enable.changed false -- call its 'changed' handler function

foo.frab $box01 $box02 -- call its 'frab' function

foo.setup.var3=10 -- set foo's setup rollout local variable, var3

foo.setup.doit.pressed() -- call 'changed' handler function for doit button in setup rollout

The local variables, functions, and structures in scripted utilities and rollouts are initialized as soon as the utility or rollout is first defined, rather than when the utility or rollout is first displayed. This allows other code to use local functions and set local values at any time after definition.


Rollout User-Interface Controls

There are 16 types of user-interface control items that you can choose from to construct your rollout. They all share the same overall syntax:

<item_type> <name> [ <label_string> ] [ <parameters> ]

The item types correspond to the types of user-interface control items you see in typical 3ds max rollouts. The types of user-interface control items are described in Rollout User-Interface Control Types.

The <name> is used to name an automatically constructed rollout local variable that will hold the value representing the control item, and is used to associate event handler functions with the control item. The optional <label_string> is used as a caption, item label, or text content depending on the control item type, as described in the topics for each type. The optional <parameters> is a sequence of keyword arguments used to set options or influence layout for the control item. The exact parameters that each control item type supports is also defined in the topics for each type.

There are properties associated with each of the user-interface control item types. The properties that are common to all user-interface control item types are described in Rollout User-Interface Controls Common Properties. 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 Rollout User-Interface Controls Common Layout Parameters.


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

$bar.pos.x = x_spinner.value

get current value from spinner x_spinner

All of the user-interface common properties except for caption (the label string value is used as the caption) can be specified as parameters when the user-interface item is constructed. For example:

button foo "Press Me!" enabled:false

The following properties are common to all user-interface items:

<ui_item>.caption String

The meaning of this property varies depending on the specific user-interface item type. If the user-interface item has a caption, this property contains the caption string. For the various types of buttons, it is the text inside the button. The default value of the caption is the label string specified in the item definition.

<ui_item>.text String

For all the user-interface items except edittext and combobox, the text property is an alias of the caption property. For edittext and combobox user-interface items, it is the text in the edit box. The default text property value for edittext user-interface items is a null string (""). The default text property value for combobox user-interface items is the selected item's text.

<ui_item>.enabled Boolean default: true

Sets whether the item is enabled for interaction when the rollout is initially opened. Disabled items appear unavailable in the rollout. All items are enabled by default, so you typically use this parameter to disable those items that should not initially be available to the user. For example, you might have some spinners that change the properties on a scene object that should not be changed until the user has picked the object, typically with a pickbutton in the rollout. You would disable the spinner in its definition, as in the following example, and enable it once the user picked an object.

spinner frab_x "Frabulate x-axis:" range:[0,100,0] enabled:false

...

frab_x.enabled=true

<ui_item>.pos Point2 default: varies

This forces the user-interface item to a fixed [x,y] pixel position in the rollout, with [0,0] at the top-left corner.

Note: 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

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: <number> default: varies

Forces the user-interface item to a specified width in pixels. Useful with buttons, for example, which otherwise self-size to their text label. Specifying an explicit width always overrides any widths computed from the text or caption properties. For example, if a spinner is given a fixed width that is too small for both label and spinner, it always aligns things to show the spinner and so might push the text out of view.

height: <number> default: varies by type

Forces the user-interface item to a specified height, typically in pixels. This lets you override the default setting height for user-interface items. For example

button foo "Stop" width:75 height:25

makes a nice big stop button.

For comboBox, dropdownList and listBox user-interface items, the height is in text rows. To have a comboBox exactly display N items, set height to N+2. To have a dropdownList exactly display N items in the list, set height to N+2. To have a listBox exactly display N items, set height to N. Height has no affect on spinner and slider user-interface items.

across: <number> default: 1

Causes this and following <number>-1 items to be laid out horizontally rather than vertically. The <number> given defines how many items to arrange horizontally. Layout then reverts to normal vertical placement. This parameter effectively divides the utility into the given number of equal-width columns and places items within them using the normal alignment for each item. The other layout parameters can be used with the across: parameter to control layout within the item's column.

pos: <point2> default: varies

This forces the user-interface item to a fixed [x,y] pixel position in the rollout, with [0,0] at the top-left corner.

Examples:

button foo "foo" align:#right --default 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 -- default alignment is right

See also

Rollout User-Interface Controls

Rollout User-Interface Controls Common Properties


Rollout User-Interface Controls Types

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:

angle

bitmap

button

checkbox

checkbutton

colorpicker

combobox

dropdownlist

edittext

groupBox

hyperLink

imgTag

label

listbox

mapbutton

materialbutton

multilistbox

popUpMenu

pickbutton

progressbar

radiobuttons

slider

spinner

timer

The following script will display all of the user-interface types in the Utilities panel:

Example:

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

)

The resulting Utilities panel rollout will appear as:

Utilities rollout showing all user-interface items


Bitmap

A bitmap item is used to place a bitmap image on the rollout. The syntax is:

bitmap <name> [ <caption> ] \ [ fileName:<filename_string> | bitmap:<bitmap> ]

The default alignment of bitmap items is #center. There is no caption or text displayed with bitmap items.

Example

bitmap the_bmp fileName:"my_pic.bmp"

Parameters

fileName:

The name of the bitmap file to load and display. The size of the bitmap image in the rollout is the bitmap file image size. The specified file name is searched for in the following directories (in order of search): current MAXScript directory, MAXScript startup directory, MAXScript directory, 3ds max bitmap directories, and then the 3ds max image directory.

bitMap:

You can specify a bitMap: creation parameter in place of the fileName: parameter that is used to specify a bitmap file. This allows you to use an existing bitmap value, such as those generated by a call to the render function. You can set bitmap to an "empty" image of a specified size by specifying a bitmap value constructor. For example:

bitmap BitmapImage bitmap:(bitmap 50 50)

Properties

<bitmap>.fileName String

The bitmap item file name as a string. You can change the image at any time by setting this property to a new name, but it will not resize the display area in the rollout; it will always be the size set from the initial image.

<bitmap>.bitmap TextureMap

A write-only property that is used to set the image displayed from a MAXScript bitmap value, as might be derived from functions like render() or selectBitmap(). You can change the image at any time by setting this property to a bitmap value, but it will not resize the display area in the rollout; it will always be the size set from the initial image.

Events

-- none --

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Button

A button item is used to place a press button on the rollout which the user can click, typically to have some task performed. The syntax is:

button <name> [ <caption> ] [ images:<image_spec_array> ] \

[ toolTip:<string> ]

The default alignment of button items is #center.

Example

button clone "Create Clones"

on clone pressed do ...

Parameters

images:

An image-specification array for providing bitmap images for the button. If this is specified, the <label> is ignored and the contents of the button are replaced with the bitmaps. The form is:

images:#(<image>, <maskImage>, <count_integer>, \

<enabled_out_image_index>, <enabled_in_image_index>, \

<disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four button states. For example:

bm1 = render camera:$cam01 outputSize:[80,60].

...

button foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use the rendered image as the button image, and

button decay images:#("dcybtns.bmp", "dcymask.bmp", 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out and in states of the button, respectively.

See also Image Buttons.

toolTip:

Provides text for a tooltip for the button; no tooltip if unsupplied.

Properties

<button>.images Array

Sets the image-specification array for the button. For example:

-- re-render, update button

bm1 = render()

foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

This property is write-only.

Events

on <button> pressed do <expr>

Called when the user clicks the button.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Checkbox

A checkbox item is used to place a check box on the rollout. The user can click to successively switch between states. The syntax is:

checkbox <name> [ <caption> ] [ checked:<boolean> ]

The default alignment of checkbox items is #left.

Example:

checkbox frab_enable "Enable frabing"

on frab_enable changed state do ...

...

if frab_enable.checked then frabulate master_obj

...

Parameters

checked:

Initial state of the check box, defaults to false (unchecked).

Properties

<checkbox>.checked Boolean

The state of the check box, on (true) or off (false).

<checkbox>.state Boolean

Synonym for .checked

Events

on <checkbox> changed <arg> do <expr>

Called when the user clicks the check box to check or uncheck it. The <arg> argument contains the new state of the check box, on (true) or off (false).

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Checkbutton

A checkbutton item is used to place a press button on the rollout that has two states, on and off, just like a check box. The user can click to successively switch between states. The syntax is:

checkbutton <name> [ <caption> ] [ highlightColor:<color> ] \

[ toolTip:<string> ] \

[ checked:<boolean> ] \

[ images:<image_spec_array> ]

The default alignment of checkbutton items is #center.

Example

checkbutton setup "Setup" checked:true tooltip:"Opens setup panels"

on setup changed state do

if state == on

then openRollout setup_pan

else closeRollout setup_pan

Parameters

checked:

Initial state of the check button, defaults to off.

highlightColor:

The background color of the check button in its pressed (or on) state, defaults to a light-gray wash in keeping with 3ds max user-interface conventions.

toolTip:

Provides text for a tooltip for the check button; no tooltip if unsupplied.

images:

An image-specification array for providing bitmap images for the check button. If this is specified, the <label> is ignored and the contents of the check button are replaced with the bitmaps. The form is:

images:#(<image>, <maskImage>, <count_integer>, \

<enabled_out_image_index>, <enabled_in_image_index>, \

<disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four check button states. For example:

bm1 = render camera:$cam01 outputSize:[80,60]

...

checkbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the check button image, and

checkbutton decay images:#("dcybtns.bmp", "dcymask.bmp", 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out and in states of the check button, respectively.

See also Image Buttons.

Properties

<checkbutton>.checked Boolean

The state of the check button, on (true) or off (false).

<checkbutton>.state Boolean

Synonym for .checked

<checkbutton>.images Array

Sets the image-specification array for the check button. For example:

-- re-render, update button

bm1 = render()

foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

This property is write-only.

Events

on <checkbutton> changed <arg> do <expr>

Called when the user clicks the check button to change its state; the <arg> argument contains the new state of the check button, on (true) or off (false).

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Colorpicker

A colorpicker item is used to place a 3ds max color selection swatch on the rollout. The user can click the swatch to display a Color Selector dialog or drag colors to or from it. The syntax is:

colorpicker <name> [ <caption> ] [ color:<color> ] \

[ fieldWidth:<number> ] [ height:<number> ] \

[ title:<string> ]

The default alignment of colorpicker items is #left.

Example

colorpicker foo "Wire color:" color:[0,0,255]

on foo changed new_col do selection.wirecolor = new_col

Parameters

color:

Initial color of the swatch. Defaults to blue.

title:

The title displayed on the Color Selector dialog. Defaults to "Choose a color".

fieldWidth:

The width in pixels of the swatch. Defaults to 40.

height:

The height in pixels of the swatch. Defaults to 16.

Properties

<colorpicker>.color Color

The current swatch color.

Events

on <colorpicker> changed <arg> do <expr>

Called when the user selects a new color in the open Color Selector dialog for this swatch or drops a new color on it. The <arg> argument contains the new color.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Combobox

A combobox item is used to place a combo box list in the rollout. This is a variant of the drop-down list in which the list is always fully displayed in the rollout with an additional edit-text box at the top of the list where the current selection is placed and may be edited. The user can scroll the list or click to select an item in the list. The syntax is:

combobox <name> [ <caption> ] [ items:<array_of_strings> ] \

[ selection:<number> ] [ height:<number> ]

The default alignment of combobox items is #left.

Example:

combobox scale_cb "Scale" items:#("1/2", "1/4", "1/8", "1/16")

on scale_cb selected i do

format "You selected %\n!" scale_cb.items[i]

scale_cb.selected = "new item text"

Parameters

text:

The text string in the edit box.

items:

The array of text strings that are the items in the list

selection:

The 1-based number of the currently selected item in the list. Defaults to 1.

height:

The overall height of the combobox in number of item lines. Defaults to 10 lines. To have a combobox display exactly N items in the list, set height to N+2.

Properties

<combobox>.caption String

The text of the optional caption above the combo box.

<combobox>.text String

The text in the edit box.

<combobox>.items Array

The item string array.

<combobox>.selection Integer

The currently selected item number, 1-based. If the items list is an empty array, this value is 0.

<combobox>.selected String

The text of the currently selected item. Can be used to replace individual items without resetting the entire items array. If the items list is an empty array, this value is undefined.

Events

on <combobox> selected <arg> do <expr>

Called when the user selects an item in the combo box list. The <arg> argument contains the new current selection item number.

on <combobox> doubleClicked <arg> do <expr>

Called when the user double-clicks an item in the list. Note that the on selected handler is always called on single clicks and on the first click of a double-click. The <arg> argument contains the number of the item double-clicked. For example

combobox foo items:#(...)

on foo doubleClicked sel do ...

on <combobox> entered <arg> do <expr>

Called when the user changes the text in the edit box then changes the focus away from the edit box. This handler is not called if the user presses ENTER. The <arg> argument contains the new text in the edit box.

on <combobox> changed <arg> do <expr>

Called for each individual character change the user performs in the edit box. This handler is not called when the user presses ENTER or changes the focus away from the edit box. The <arg> argument contains the new text in the edit box.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Dropdownlist

A dropdownlist item is used to place a drop-down list in the rollout. The user can click open the list and scroll or click again to select an item in the list. The syntax is:

dropdownlist <name> [ <caption> ] [ items:<array_of_strings> ] \

[ selection:<number> ] [ height:<number> ]

The default alignment of dropdownList items is #left.

Example:

dropdownlist scale_dd "Scale" items:#("1/2", "1/4", "1/8", "1/16")

on scale_dd selected i do

format "You selected %\n!" scale_dd.items[i]

Parameters

items:

The array of text strings that are the items in the list.

selection:

The 1-based number of the currently selected item in the list. Defaults to 1.

height:

The overall height of the dropdownlist in number of item lines. Defaults to 10 lines. To have a dropdownlist exactly display N items in the list, set height to N+2.

Properties

<dropdownlist>.items Array

The item string array.

<dropdownlist>.selection Integer

The currently selected item number, 1-based. If the items list is an empty array, this value is 0.

<dropdownlist>.selected String

The text of the currently selected item. Can be set to replace individual items without resetting the entire items array. If the items list is an empty array, this value is undefined.

Events

on <dropdownlist> selected <arg> do <expr>

Called when the user selects an item in the drop-down list. The <arg> argument contains the new current selection item number.

Example:

rollout test "t"
(

dropdownlist dd "dd" items:#("1","2","3","4","5","6","7","8","9","10") height:6
label l "L"

)
rof=newrolloutfloater "A" 200 200
addrollout test rof

you will get 5 items in the dropdown list. Change height to 5, and you get 3.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Edittext

An edittext item is used to place an editable text field where the user can type and edit text. The syntax is:

edittext <name> [ <caption> ] [ text:<string> ] \

[ fieldWidth:<integer> ] [bold:<boolean> ]

The default alignment of edittext items is #left.

Example:

edittext prefix_txt "Name prefix:" fieldWidth:70

on prefix_txt entered text do ...

...

new_obj = copy master pos:[x,y,z] prefix:prefix_txt.text

...

Parameters

text:

The text string in the edit box.

fieldWidth:

The width in pixels of the edit box. By default, the width is set to be from just after the caption text to the right margin of the rollout.

bold:

If set to true, the text string in the edit box is displayed in bold format, if set to false, in normal, non-bold format. The default value is false.

Properties

<edittext>.text String

The text in the edit box.

<edittext>.caption String

The text of the optional caption next to the edit box.

<edittext>.bold Boolean

If true, the text is displayed in bold format, if false, in normal, non-bold format.

Events

on <edittext> changed <arg> do <expr>

Called each time the user changes the text in the edit box; the <arg> argument contains the new text in the edit box.

on <edittext> entered <arg> do <expr>

Called when the user enters text in the edit box and then presses ENTER or TAB to move the cursor out of the field. The <arg> argument contains the new text in the edit box.

If you enter a string in the edit box and then press ENTER, the on changed handler is called once per character and once for the ENTER. The on entered handler is just called once, for the ENTER.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Label

A label item is used to place static text on the rollout, perhaps a label for another item or a text message. The syntax is:

label <name> [ <string> ]

The default alignment of label items is #center.

Example:

label lab1 "Please choose an object:"

Properties

No additional properties for label.

Events

-- none --

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Listbox

A listbox item is used to place a list box in the rollout. This is another variant of the drop-down list in which the list is always fully displayed in the rollout. Unlike combobox, it has no edit-text field at the top and it is just a simple scrollable list. The user can scroll the list or click to select an item. The syntax is:

listbox <name> [ <caption> ] [ items:<array_of_strings> ] \

[ selection:<number> ] [ height:<number> ]

The default alignment of listbox items is #left.

Example:

listbox selns items:obj_name_array

on selns selected i do

copy obj_array[i] pos:[rand_x, rand_y, rand_z]

selns.selection = 2

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

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Mapbutton

A mapbutton item is used to place a button in the rollout that will display the 3ds max Material/Map Browser dialog when clicked. Only texture maps will be displayed in the Material/Map Browser dialog. The syntax is:

mapbutton <name> [ <caption> ] [ map:<texturemap> ] \

[ images:<image_spec_array> ] [ toolTip:<string> ]

The default alignment of mapbutton items is #center.

Example:

label sbm_lbl "Background Map:"

mapbutton choosemap "<<none>>" tooltip:"Select Background Map"

on choosemap picked texmap do

(

environmentmap = texmap

choosemap.text=classof texmap as string

)

Parameters

map:

The initial textureMap value returned by the map property before the user has selected a texture map using the mapbutton. Defaults to undefined.

images:

An image-specification array for providing bitmap images for the mapbutton. If this is specified, the <label> is ignored and the contents of the mapbutton are replaced with the bitmaps. The form is:

images:#(<image>, <maskImage>, <count_integer>, \

<enabled_out_image_index>, <enabled_in_image_index>, \

<disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four mapbutton states. For example:

bm1 = render camera:$cam01 outputSize:[80,60]

...

mapbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the mapbutton image, and

mapbutton decay images:#("dcybtns.bmp", "dcymask.bmp", 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out and in states of the mapbutton, respectively.

See also Image Buttons.

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.

Note: 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

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Materialbutton

A materialbutton item is used to place a button in the rollout that will display the 3ds max Material/Map Browser dialog when clicked. Only materials will be displayed in the Material/Map Browser dialog. The syntax is:

materialbutton <name> [ <caption> ] [ material:<material> ] \

[ images:<image_spec_array> ] \

[ toolTip:<string> ]

The default alignment of materialbutton items is #center.

Example:

label smtl_lbl "Set selected object's material to:"

materialbutton choosemtl "Pick Material"

on choosemtl picked mtl do

(

print mtl

if $ != undefined do $.material=mtl

)

Parameters

material:

The initial material value returned by the material property before the user has selected a material using the materialbutton. Defaults to undefined.

images:

An image-specification array for providing bitmap images for the materialbutton. If this is specified, the <label> is ignored and the contents of the materialbutton are replaced with the bitmaps. The form is:

images:#(<image>, <maskImage>, <count_integer>, \

<enabled_out_image_index>, <enabled_in_image_index>, \

<disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four materialbutton states. For example:

bm1 = render camera:$cam01 outputSize:[80,60]

...

materialbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the materialbutton image, and

materialbutton decay images:#("dcybtns.bmp", "dcymask.bmp", 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out and in states of the materialbutton, respectively.

See also Image Buttons.

toolTip:

Provides text for a tooltip for the materialbutton. No tooltip if unsupplied.

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.

Note: 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

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


MultiListBox

A MultiListBox item is used to place a list box in the rollout. This is a variant of the ListBox in which multiple items in the list can be selected. The syntax is:

MultiListBox <name> [ <caption> ] [ items:<array_of_strings> ] \

[ selection:{<bitarray> | <number_array> | <number>} ] \

[ height:<number> ]

The default alignment of MultiListBox items is #left.

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.

Notes

There isn't a way to deselect all the items in the list by clicking in the list somewhere. To clear the list selection you will need a "Clear Selection" button that sets selection=#{}.


Pickbutton

A pickbutton item is used to place a scene object-picker button on the rollout. It operates like a normal pick button in the 3ds max user interface, turning light-green when pressed and causing an object-pick mode to be entered. The user can then choose a scene object by clicking on it. The pick mode exits and the button returns to its unpressed state. The user can right-click to cancel the pick mode. The syntax is:

pickbutton <name> [ <caption> ] [ message:<string> ] \

[ filter:<function> ] [ toolTip:<string> ]

The default alignment of pickbutton items is #center.

Example:

fn foo_filt obj = findString obj.name "foo" == 1

pickbutton chooseit "Select master object" filter:foo_filt

on chooseit picked obj do

(

master = obj

chooseit.text = obj.name

)

Parameters

message:

The optional text to be displayed in the 3ds max status line while in the pick mode. Default is no message.

filter:

The optional filter function that will be called to test the eligibility of the scene object under the cursor for picking. It must be a function of one argument, which will be the object under test, and return true if the object is eligible or false if not. For example, the following filter function allows only objects whose names begin with "foo" to be pickable:

fn foo_filt obj = findString obj.name "foo" == 1

Default is no filtering.

toolTip:

Provides text for a tooltip for the button. No tooltip if unsupplied.

Properties

<pickbutton>.object Node

The last object picked using the pickbutton, undefined if no object has been picked. This property is read-only.

Events

on <pickbutton> picked <arg> do <expr>

Called when the user selects an object in the scene while in the pickbutton pick mode. The <arg> argument contains the selected object. The handler is not called if the user cancels out of the pick mode.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


ProgressBar

A progressBar item is used to place a progress bar on the rollout. The syntax is:

progressBar <name> [ value:<number> ] [ color:<color> ] \

[ orient:<name> ]

The default alignment of progressBar items is #left.

Example:

button doit "Process Scene"

progressbar doit_prog color:red

on doit pressed do

(

for i = 1 to objArray.count do

(

doit_prog.value = 100.*i/objArray.count

...

)

doit_prog.value = 0

)

Parameters

value:

The initial progress percentage value (0 – 100). The default value is 0. This is an Integer value.

color:

The color of the progress bar. The default color value is [30,10,190].

orient:

Specifies whether the progress bar should fill from left to right (orient:#horizontal) or bottom to top (orient:#vertical). Default value is #horizontal.

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

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Radiobuttons

A radiobuttons item is used to place a set of radio buttons on the rollout, only one of which can be checked at a time. The user can click different buttons in the set to change states. The syntax is:

radiobuttons <name> [ <caption> ] labels:<array_of_strings> \

[ default:<number> ] [ columns:<number> ]

The default alignment of radiobuttons items is #center.

Example:

radiobuttons copy_type labels:#("copy", "instance", "reference")

radiobuttons which_obj labels:obj_name_array -- computed label array

on copy_type changed state do ...

...

copyfn = case copy_type.state of

(

1: copy

2: instance

3: reference

)

...

Parameters

labels:

An array of strings that specifies the number of radio buttons and the text label for each one.

default:

The number of the radio button initially selected. Default is 1.

columns:

Number of columns across in which to arrange the buttons. By default, MAXScript will attempt to lay out all the radio buttons side-by-side on one line, and if they won't fit, vertically in a single column. You can force the layout system to array the buttons in multiple columns using this parameter. Each column is given the same width, which is the width of the widest label in all columns and it left-adjusts the radio buttons in these columns.

Properties

<radiobuttons>.state Integer

The 1-based number of the currently selected radio button in the order specified in the labels: array.

Events

on <radiobuttons> changed <arg> do <expr>

Called when the user clicks one of the radio buttons in the set. The <arg> argument contains the new state of the radio buttons array, which is the 1-based number of the newly selected button.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Slider

A slider item is used to place a slider on the rollout, as an alternative to a spinner. The user can drag the slider's pointer around to set its value. The syntax is:

slider <name> [ <caption> ] [ range:[min,max,val] ] \

[ type:#float ] [ ticks:10 ] \

[ orient:#horizontal ]

The default alignment of slider items is #center.

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

Note: If you are using a slider to interactive adjust a property of an on-screen object, you can improve the interactive speed by moving the object to the foreground plane. Objects placed in the foreground plane are redrawn individually and so interactive changes to them are much faster. An object is moved to the foreground or background plane using the flagForeground() method:

flagForeground <node> <boolean> -- mapped

The boolean argument puts the scene node(s) into the foreground plane if true, or into the background plane if false.

You should be judicious in putting objects in the foreground plane, because putting too many objects in the foreground plane reduces the foreground plane's effectiveness. Remember to return objects to the background plane when you don't need to interactively control them any more.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Spinner

A spinner item is used to place a 3ds max value spinner on the rollout. The user can drag the spinner arrows or type values into the spinner edit field. The syntax is:

spinner <name> [ <caption> ] [ range:[min,max,val] ] \

[ type:<name> ] [ scale:<float> ] \

[ fieldWidth:<integer> ] [ controller(<controller>) ]

The default alignment of spinner items is #right.

Example:

spinner frab_amt "Frab %:" range:[0,100,10] type:#integer

spinner ball_radius "Ball radius" controller:($ball.radius.controller)

on frab_amt changed val do frabulate selection val

Parameters

range:

A Point3 value containing the minimum, maximum, and initial values for the spinner in the x, y, and z components, respectively. Defaults to [0,100,0].

type:

The type of the spinner: #float, #integer, or #worldunits. Defaults to #float. If type is #worldunits, the value is displayed in the current 3ds max display units, but the value is always in internal system units.

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 can be a new controller or 'undefined' to disconnect. 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.

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

Note: If you are using a spinner to interactive adjust a property of an on-screen object, you can improve the interactive speed by moving the object to the foreground plane. Objects placed in the foreground plane are redrawn individually and so interactive changes to them are much faster. An object is moved to the foreground or background plane using the flagForeground() method:

flagForeground <node> <boolean> -- mapped

The boolean argument puts the scene node(s) into the foreground plane if true, or into the background plane if false.

You should be judicious in putting objects in the foreground plane, because putting too many objects in the foreground plane reduces the foreground plane's effectiveness. Remember to return objects to the background plane when you don't need to interactively control them any more.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Timer

A timer item generates tick events at set intervals. Timer is unlike the remainder of the user-interface items as it is not a visible control. Timer lets the user interface react, animate, or change without user interaction, such as having animations playing on the rollout, checking for certain conditions or events before continuing, displaying nag/splash screens, and so on. The syntax is:

timer <name> [ interval:<number> ] [ active:<boolean> ]

Example:

utility test "test1"

(

timer clock "testClock" interval:400

label test "1"

on clock tick do

(

valUp = (test.text as integer)+1

test.text = valUp as string

)

)

Parameters

interval:

An integer value specifying the time in milliseconds between tick events. Default value 1000 (1 second).

active:

Specifies whether the timer emits tick events. Default value true.

Properties

<timer>.interval Integer

Integer value specifying the time in milliseconds between tick events.

<timer>.active Boolean

Specifies whether the timer emits tick events (true) or not (false). When first set to true, the first tick event is generated in interval milliseconds.

Events

on <timer> tick do <expr>

Called when timer ticks.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


Image Buttons

Four rollout user-interface item types, button, checkbutton, mapbutton, and materialbutton, can be either simple text buttons containing text labels or image buttons inside of which bitmaps can be displayed instead of text. The images to be displayed in these buttons are specified using the definition-line parameter images:. The parameter form is:

images:#(<image>, <maskImage>, <count_integer>, \

<enabled_out_image_index>, <enabled_in_image_index>, \

<disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four button states. For example:

bm1 = render camera:$cam01 outputSize:[80,60]

...

checkbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the button image.

If the image or maskImage is specified as a file name, the bitmap file is searched for in the following directories (in order of search): current MAXScript directory, MAXScript startup directory, MAXScript directory, 3ds max bitmap directories, and then the 3ds max image directory.

There are four images that can be specified, one for each of the possible button states, enabled-out, enabled-in, disabled-out, and disabled-in. These images are taken from a single bitmap file or MAXScript bitmap value in which a number of images are stored side-by-side. This bitmap, containing one or more images to use for the button, is called the imagelist. All the sub-images in such an imagelist are taken to be the same width and you specify which image is used for which state by providing an image-index into the bitmap. This means you can store the images for all the states of many buttons in one file, specifying different indexes for the different buttons.

You can also specify a black-and-white mask image used to mask the image display into the buttons. It is given in the same imagelist form and the mask image indexes must be the same as the images they correspond to. Black pixels in the mask let the corresponding image pixel show; white pixels hide corresponding image pixels and show the default background color for the button. If there is no mask file, supply the value undefined for the mask file name.

Bitmap files without full path names are searched for in the Startup scripts directory, then the scripts directory, then the 3ds max images directory, then the 3ds max executables directory, and then the directories in the PATHS environment variable.

You can change the images in a button by setting the .images property of these user-interface items. For example:

-- re-render, update button

bm1 = render camera:$cam01 outputSize:[80,60]

foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

Example:

checkbutton decay images:#("dcybtns.bmp", "dcymask.bmp", 6, 1, 4, 1, 4)

In this example, the images are in a file dcybtns.bmp and the masks in dcymask.bmp. These bitmap files each have six images across and the out-state is image 1 and the in-state is image 4. Both enabled and disabled here are given as the same image, presumably because this particular button will never be disabled.


Scripted Right-Click Menus

MAXScript provides a set of classes and functions and some special syntax to allow you to construct custom right-click menus that can be incorporated into the existing 3ds max user interface. You typically use right-click menus to provide quick access to a selection of tools you have written in MAXScript. These tools would typically have no user interface, however you can create dialogs or rollout floater windows in a right-click menu to display a user interface.

A scripted right-click menu is created using the RCMenu definition construct in MAXScript, and then you register the right-click menu with 3ds max. The top-level definition syntax is as follows:

rcmenu <var_name> ( <rcmenu_body> )

where:

<var_name> is the name of an automatically created global variable to hold the rcmenu value that represents the right-click menu.

<rcmenu_body> is enclosed in the required parentheses and is a sequence of clauses that define the menu items that will appear in the utility, along with functions and event handlers that process user interactions. These clauses are defined in detail in RCMenu Clauses.

Methods

popUpMenu <RCMenu> [pos:<Point2>] [rollout:<Rollout>] [align:<key>]

This method will popup a menu anywhere on the screen. The controls are as follows:

<RCMenu>: Any RCMenu defined. It does not have to be registered.

[pos:<Point2>]: The point where the menu pops up, either relative to the Rollout or the screen. (Default: popup from current mouse position.)

[rollout:<Rollout>]: This will make the menu popup from a rollouts local coordinate system. Specifying undefined will cause the menu to popup relative to the upper left corner of the screen. (Default: undefined)

[align:<key>]: Can be one of the following (Default: #align_topleft):

#align_topleft

#align_topcenter

#align_topright

#align_bottomleft

#align_bottomcenter

#align_bottomright

#align_vcenterleft

#align_vcentercenter

#align_vcenterright

The following methods let you register and unregister scripted right-click menus:

registerRightClickMenu <rcmenu>

registers the specified right-click menu

unRegisterRightClickMenu <rcmenu>

unregisters the specified right-click menu

unRegisterAllRightClickMenus()

unregisters all right-click menus

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.

Script:

rcmenu MyRCmenu

(

menuItem mi_cs "Cast Shadows" checked:false

menuItem mi_rs "Receive Shadows" checked:false

--

on MyRCmenu open do

(

local sel = (selection.count == 1)

-- Enable if only one object is selected

mi_cs.enabled = mi_rs.enabled = sel

-- Set check state of items

if sel do

(

mi_cs.checked = $.castShadows

mi_rs.checked = $.receiveShadows

)

)

-- set up event handlers for items

on mi_cs picked do $.castShadows = (not $.castShadows)

on mi_rs picked do $.receiveShadows = (not $.receiveShadows)

)

-- register the rcmenu

registerRightClickMenu MyRCmenu

You can register as many scripted right-click menus as you like. Each scripted right-click menu registered is appended to the right-click menu window. If a scripted right-click menu with the same name is registered twice, the old one is over written by the new one.

If a runtime error occurs while executing a scripted right-click menu, an error message is displayed in Listener. The right-click menu will not be disabled.


RCMenu Clauses

The <rcmenu_body> of a right-click menu definition is made up of a sequence of scripted right-click menu clauses as follows:

<rcmenu_body> ::= { <rcmenu_clause> }+

Scripted right-click menu clauses define the components of a scripted right-click menu and can be one of three basic things:

  • Local variables, functions or structure definitions are variables, functions, and structures whose scope is the scripted right-click menu. These locals will exist as long as the scripted right-click menu value exists. The scripted right-click menu value will exist until the scripted right-click menu value is redefined or deleted. Local variables are particularly useful for storing working data associated with the right-click menu such as picked objects.

  • User-interface items are displayed in the right-click menu, such as menu items, separators, and submenus.

  • 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 Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code and Accessing Locals and Other Items in a Rollout from External Code. In both utility rollouts and scripted right-click menus, the name given to a user-interface item is used to name an automatically constructed local variable that will hold the value representing the item. It is also used to associate event handler functions with the item. One difference between the scoping of these variables is that they are local to the rollout in utility rollouts, and local to the scripted right-click menu in scripted right-click menus. This means that all user-interface items in a scripted right-click menu must have a unique name within the scripted right-click menu, even for those items present in a subMenu.

Formally, the syntax of a <rcmenu_clause> is defined as follows:

<rcmenu_clause> ::= <local_variable_decl> |

<local_function_decl> |

<local_struct_decl> |

<user_interface_item> |

<event_handler>

Locals

A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly the same as local variable, function, and structure definitions in MAXScript:

<local_variable_decl> ::= local <decl> { , <decl> }

<decl> ::= <name> [ = <expr> ] -- optional initial value

<local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr>

<local_struct_decl> ::= struct <name> ( <member> { , <member> } )

<member> ::= ( <name> [ = <expr> ] | <local_function_decl> )

Examples of the above (in order) are:

local numSelected

local numSelected = 0

fn onlyOneSelected = selection.count == 1

struct parents (mother="", father="")

Global variables cannot be declared as a scripted right-click menu clause, however they can be declared within event-handler scripts. If you need to ensure that a variable name references a global variable, declare the variable name as global immediately before defining the right-click menu in your script.

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 Scope of Variables.

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 RCMenu User-Interface Items.

Event Handlers

An <event_handler> is a special function definition local to a scripted right-click menu that you provide to handle the processing you want to occur when a user clicks on a menu item. This user action generates a named event and any event handler you supply for that event is called when the action occurs. The syntax for defining a handler is as follows:

on <item_name> <event_name> do <expr>

The <item_name> specifies the name of the item for which this handler is connected. The <event_name> specifies the type of event to be handled. There is only one type of user-interface item event:

picked

The picked handler expression is executed when a menu item is picked from the right-click menu. Any MAXScript action like creating a object, adding a modifier, and so on can be performed in this expression.

In addition to the event handlers you specify for particular menu items in a right-click menu, you can define a handler function that is called when the entire right-click menu is first opened by the user. This event handler is useful for initialization code. The syntax for this event handler is as follows:

on <rcmenu> open do <expr>

See also

Scripted Right-Click Menus


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

separator

subMenu


menuItem

A menuItem is used to place a pickable item in the right-click menu. The syntax for a menuItem is:

menuItem <name> <label> [ checked:<boolean> ] [ enabled:<boolean> ] [ filter:<function> ]

Parameters

name:

Used to refer to when writing an event handler.

label:

The string that appears in the right-click menu.

checked:

Specifies if a check mark appears before the label in the right-click menu. If true the item is checked, otherwise the item is unchecked.

enabled:

Specifies if the item is enabled for interaction when the right-click menu is opened. If true the item is enabled, otherwise the item is disabled and appears unavailable.

filter:

A function that returns a Boolean value. The filter function is evaluated when the right-click menu is first opened. If the filter function returns true the menuItem appears in the menu, otherwise it is not displayed.

Properties

<menuitem>.text String

The string that appears in the right-click menu.

<menuitem>.checked Boolean

Specifies if a check-mark appears before the label in the right-click menu. If true the item is checked, otherwise the item is unchecked.

<menuitem>.enabled Boolean

Specifies if the item is enabled for interaction when the right-click menu is opened. If true the item is enabled, otherwise the item is disabled and appears as unavailable.

Events

on <menuitem> picked do <expr>

Called when the user clicks the menu item.

Example:

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

Scripted Right-Click Menus


separator

A separator is used to place a separator line in the right-click menu, and is normally used to group menu items. The syntax for a separator is:

separator <name> [ filter:<function> ]

Parameters

name:

Used to name an automatically constructed local variable that will hold the value representing the separator.

filter:

A function that returns a Boolean value. The filter function is evaluated when the right-click menu is first opened. If the filter function returns true the separator appears in the menu, otherwise it is not displayed.

Example:

rcmenu MyRCmenu

(

fn flt_objects = ($ != undefined) -- objects filter

menuItem mi_cs "Cast Shadows" checked:false

menuItem mi_rs "Receive Shadows" checked:false

-- add only if one or more objects are selected

separator sep1 filter:flt_objects

menuItem mi_st "Scale Twice" filter:flt_objects

menuItem mi_sh "Scale Half" filter:flt_objects

-- event handlers would go here...

)

registerRightClickMenu MyRcmenu -- register the rcmenu

See also

RCMenu Clauses

Scripted Right-Click Menus


subMenu

A subMenu is used to place an item in the right-click menu that, if the cursor is placed on, opens a submenu containing additional user-interface items. The syntax for a subMenu is:

subMenu <label> [ filter:<function> ] ( <submenu_body> )

The <submenu_body> of a subMenu definition is made up of a sequence of RCMenu clauses as follows:

<submenu_body> ::= { <rcmenu_clause> }+

Parameters

label:

The string that appears in the right-click menu.

filter:

A function that returns a Boolean value. The filter function is evaluated when the right-click menu is first opened. If the filter function returns true the subMenu appears in the menu, otherwise it is not displayed.

Example:

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

menuItem mi_bend "Bend"

menuItem mi_twist "Twist"

-- Add shape only modifiers

separator sep3 filter:flt_shapes

subMenu "Shape" filter:flt_shapes -- begin nested subMenu

(

menuItem mi_extrude "Extrude"

menuItem mi_EditSpline "Edit Spline"

)

)

-- event handlers would go here...

)

registerRightClickMenu MyRcmenu -- register the rcmenu

See also

RCMenu Clauses

Scripted Right-Click Menus


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 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 Rollout Floater Windows, and create and install the user-interface items in the rollout(s) as described in Rollout User-Interface Controls.

Define a Macro Script using the following syntax:

macroScript <name> [ category:<string> ]

[ buttonText:<string> ]

[ toolTip:<string> ]

[ icon:#(<string>, <index>) | icon:<string> ]

[ silentErrors:<boolean> ]

( <macro_script_body> )

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 appropriate category list in the Customize User-Interface dialog. The following figure shows a Customize User Interface dialog containing the previous two Macro Scripts.

If a tooltip is specified, that tooltip is the name shown in the Customize User Interface dialog. If a tooltip is not specified, <name> is the name shown. 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.

Note: You can use non-alpha numeric characters to define any of the argument strings. This includes support for escaped double quote characters: \".

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 internalCategory argument is intended to identify operations in .cui, .mnu, and .kbd files.

The toolTip: argument specifies the tooltip for the button. If no tooltip is specified, <name> is displayed for the button.

The buttonText: argument specifies the text that will appear in the button, and the icon: argument specifies the icon that will appear in the button. You can choose in the Customize User Interface dialog whether the buttonText or icon appears in the button. If no buttonText: argument is specified, the Macro Script name is used as the buttonText.

The icon: argument specifies the icon bitmap file and the icon image within the icon bitmap file. The icon bitmap file must be located in the current 3ds max user-interface directory. Icon bitmap files have a base name, such as "MyToolbar", followed by a suffix, such as "_24i.bmp", that specifies the individual icon size and icon bitmap file type. The icon: argument string is just the base name, with no extensions present. This base name is the name shown in the Image Group list in the Customize User-Interface dialog. Each icon bitmap file can have any number of individual icons, lined up side-by-side in the file. If the icon bitmap file contains multiple icons, <index> specifies which icon in the icon bitmap file to use. The left-most icon has an <index> of 1. The 3ds max internal icons (Image Group Internal in the Customize User-Interface dialog) are not stored in an icon file, and are referenced by using an empty string as the icon: argument.

So, the icon: argument can be either a two-element array containing the icon bitmap file's base name as a string and the icon's index in that file, or just a base name string, with the index 1 assumed. For example:

macroScript Box category:"Objects" tooltip:"Box"

icon:#("standard", 1) -- use first icon in standard

(

StartObjectCreation Box

)

macroScript Sphere category:"Objects" tooltip:"Sphere"

icon:#("", 2) -- use second icon in internal icons

(

StartObjectCreation Sphere

)

macroScript Cone category:"Objects" tooltip:"Cone"

icon:"myicon" -- use first icon in myicon

(

StartObjectCreation Cone

)

See Creating Icon Bitmap Files for more information.

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> can be one of two forms. The body can be either a single MAXScript expression, or a set of event handlers. An <event_handler> is a special function definition local to the macroscript that handles events generated by 3ds max 4. The syntax for defining an event handler is as follows:

on <event_name> do <expr>

The valid <event_name> are:

isChecked - if <expr> returns true and the macroscript item is in a menu or quad menu, a check mark is placed next to the macroscript item. If the macroscript is a toolbar button, the button will appear as "pressed in". The do is optional for this event handler. If this event handler is not specified, the item will not be checked.

isEnabled - if <expr> returns false and the macroscript item is in a menu or quad menu, the macroscript item will not appear in the menu or quad menu. If the macroscript is a toolbar button, the button will be disabled. The do is optional for this event handler. If this event handler is not specified, the item will be enabled.

isVisible - if <expr> returns false and the macroscript item is in a menu or quad menu, the macroscript item will not appear in the menu or quad menu. If the macroscript is a toolbar button, this handler has no affect. The do is optional for this event handler. If this event handler is not specified, the item will be visible.

execute - the expression evaluated when the menu or quad menu item is chosen, or the toolbar button clicked. A runtime error will be generated if this event handler is not specified.

Examples:

macroScript Free_Camera

category:"Lights and Cameras"
internalcategory:"Lights and Cameras"
tooltip:"Free Camera"
buttontext:"Free Camera"
Icon:#("Cameras",2)

(

on execute do StartObjectCreation FreeCamera
on isChecked return (mcrUtils.IsCreating FreeCamera)

)

MacroScript SubObject_Vertex

ButtonText:"Vertex"
Category:"Modifier Stack"
internalCategory:"Modifier Stack"
Tooltip:"Vertex Sub-object Mode"
Icon:#("SubObjectIcons",1)

(

On IsChecked (SubObjectLevel == 1 and filters.CanSwitchTo_Vertex())
On IsEnabled Filters.CanSwitchTo_Vertex()
On IsVisible Filters.CanSwitchTo_Vertex()
On Execute do
(

If SubObjectLevel == undefined then Max Modify Mode
If SubObjectLevel != 1 then SubObjectLevel = 1 Else SubObjectLevel = 0

)

)

The <macro_script_body> 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 Scope of Variables 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 the Listener window onto a toolbar to make a button that does the sequence of events just recorded. Remember that tabbed elements on the Shelf are toolbars and can accept dropped text. MAXScript will automatically enclose the text in a Macro Script definition with a Macro Script name of DragAndDrop-MacroN, where N is a number that will make the Macro Script name unique. The category will be DragAndDrop and no tooltip is specified. As with Macro Scripts defined in the Listener window, a file will automatically be created to contain the Macro Script definition. This file is stored in the MacroScripts directory under the current user-interface directory.

  • A Macro Script can be defined using the macros.new() method described next. As with Macro Scripts defined in the Listener window, a file will automatically be created to contain the Macro Script definition. This file is stored in the MacroScripts directory under the current user-interface directory.

If you move or delete a file that contains a Macro Script definition that has been loaded, and try to execute the Macro Script, you will get an error message. Further, if you edit a file containing Macro Script definitions, take care to save and re-evaluate the entire file so any other Macro Scripts defined in that file will have their file pointer updated. If you don't do this, you may get an error message saying the currently loaded definition no longer matches its file.

If you reevaluate a Macro Script definition, any button using that Macro Script will see any changes you make.

Any macroScript definition evaluated in MAXScript or created by dropping text onto a toolbar has a separate definition .mcr file created in the MacroScripts directory under the current user-interface directory (typically UI\MacroScripts). The name of the file is <category_name>-<macro_name>.mcr, for example,

DragAndDrop-Macro12.mcr for macroScript Macro12 category:"DragAndDrop"

NURBS-Map_Updater.mcr for macroScript Map_Updater category:"NURBS"

If you evaluate a macroScript definition in the Listener or drop text on a toolbar, its recorded definition file is this backing file in UI\MacroScripts. This definition file is the one that gets opened if you hit Edit Macro Script in the CUI customize menus or dialogs. For macroScript definitions evaluated in Listener, this means the same definition will be updated each time you evaluate it, rather than having separate backing file for each evaluation.

If you evaluate macroScript definitions in a .ms or .mcr file that does not already reside in the UI\MacroScripts directory, a copy for each will be placed in a separate file in UI\MacroScripts, but the recorded definition file will be the original source file, so that hitting Edit Macro Script will go to that file.

This means that if any buttons containing such macroScript definitions are added to toolbars in the startup.cui file, the backing .mcr file in UI\MacroScripts will be used as its definition at the next 3ds max startup. When you start 3ds max, the macroScript definitions will taken from the backing files in UI\MacroScripts. If these Macro Scripts are also defined in MAXScript startup script files, they will be re-defined at MAXScript startup and so the definition file of record will be updated to point to the script file.

MAXScript provides several methods that allow you to access and run Macro Scripts from within a script. These Macro Script functions are in a structure package named macros. The Macro Script methods are:

macros.load [ <path_name_string> ]

Loads all of the Macro Script definition (.mcr) files in the current user-interface directory path, or in directory path specified by <path_name_string>. This method does not change the current user-interface directory path. You can get the current user-interface directory path with the function:

local ui_dir = cui.getDir ()

macros.new <name_string> <category_string> <toolTip_string> \

<buttonText_string> <body_string>

Creates a new Macro Script with the specified name and category. A file will automatically be created to contain the definition. This file is stored in the current user-interface directory. Returns an integer Macro Script ID value that uniquely identifies the new Macro Script.

macros.run <category_string> <name_string>

macros.run <macro_id_integer>

Executes the specified Macro Script. The Macro Script is identified by either its category and name, or by its unique Macro Script ID value.

macros.edit <category_string> <name_string>

macros.edit <macro_id_integer>

These methods will open the Macro Script definition (.mcr) file that defines the specified Macro Script in a script Editor window. The Macro Script is identified by either its category and name, or by its unique Macro Script ID value.

For example:

macros.load "f:/gametools/macros"

macros.edit "objects" "box"

macros.run 132

macros.run "modifiers" "bend"

The following Macro Script will save the active viewport's image to a bitmap file.

Example:

MacroScript GrabViewport category:"Tools" tooltip:"Grab Viewport"

(

---------------------------------------------------------------------

--GRABVIEWPORT MACROSCRIPT

--Created:3/23/99

--Edited:4/28/99

--by Borislav Petrov

--bobo@email.archlab.tuwien.ac.at

---------------------------------------------------------------------

--Snapshot Active Viewport to Bitmap

--Filename in format:

--VPGRAB_MaxFileName_ViewportName_CurentFrame.ImageFormatExtension

---------------------------------------------------------------------

--

--Init Variables

local grab_bmp --bitmap to put the snapshot into

local bmp_name --name of the bitmap to save

local get_viewport_name --viewport name

local gac,gct,mfn --variables to hold ActiveCamera, CurrentTime, MaxFileName

--

--Start Macro

grab_bmp = gw.getViewportDib() --get the viewport bitmap into variable

get_viewport_name = viewport.GetType() --get viewport name

gvn = get_viewport_name as string --convert viewport name to string

gvn = substring gvn 6 (gvn.count-5) --cut the string

if gvn == "camera" then --if the remaining string is "camera"

(

gac = getActiveCamera() --get the camera

gvn = gac.name --get the name of the camera

)

mfn = MaxFileName --get max file name

if mfn == "" then --if there is no name

mfn = "Untitled" --use "Untitled"

else

mfn = getFileNameFile mfn --use the file name without .MAX extension

gct = SliderTime as string --get current frame time

bmp_name = "VPGRAB_"+ mfn +"_" +gvn + "_" + gct --build the output file name

--Display file save dialog

bmp_name = getSaveFileName caption:"Save Viewport to:" filename:bmp_name \

types:"BMP(*.bmp)|*.bmp|TIFF(*.tif)|*.tif|JPG(*.jpg)|*.jpg|TGA(*.tga)|*.tga|"

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.

Example:

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

function get_names name a = append a name

function existFile fname = (getfiles fname).count != 0

-- create the rollout definition

rollout r_size "Render Parameters"

(

local p = 95

local p2 = p+78

group "Time Output"

(

radiobuttons r_time columns:1 align:#left \ labels:#("Single","Active Time Segment","Range:")

spinner nth "Every Nth Frame:" pos:[215,24] fieldwidth:50 \ type:#integer range:[0,10000,1] enabled:false

spinner r_from fieldwidth:60 pos:[75,56] type:#integer \ range:[0,10000,1] enabled:false

spinner r_to "To:" fieldwidth:60 pos:[152,56] type:#integer \ range:[0,10000,100] enabled:false

)

group "Render Size"

(

spinner rw "Width " fieldwidth:60 pos:[15,p+08] \ type:#integer range:[0,10000,320]

spinner rh "Height " fieldwidth:60 pos:[12,p+32] \ type:#integer range:[0,10000,240]

spinner aspect "Aspect " fieldwidth:60 pos:[10,p+56] \ type:#float range:[0,20,1.0]

button s160 "160x120" pos:[125,p+06] width:75 height:19

button s256 "256x243" pos:[125,p+30] width:75 height:19

button s320 "320x240" pos:[205,p+06] width:75 height:19

button s512 "512x486" pos:[205,p+30] width:75 height:19

button s640 "640x480" pos:[285,p+06] width:75 height:19

button s720 "720x486" pos:[285,p+30] width:75 height:19

button conf_render "Configure" pos:[125,p+54] width:115 height:19

button wipe "Purge Files" pos:[245,p+54] width:115 height:19

button go "Render" pos:[125,p+78] width:235 height:19

)

label abt0 "Render to RAM" pos:[8,p2+31]

label abt1 "Version 0.2a" pos:[8,p2+46]

label abt2 "Alexander Esppeschit Bicalho" pos:[225,p2+31]

label abt3 "abicalho@brasilmail.com" pos:[249,p2+46]

-- define the rollout event handlers

on wipe pressed do

(

local tempfilename_a = (getdir #image) + "\\ramplayertemp_a.avi"

local tempfilename_b = (getdir #image) + "\\ramplayertemp_b.avi"

if existfile tempfilename_a then deletefile tempfilename_a

if existfile tempfilename_b then deletefile tempfilename_b

)

on r_time changed state do

(

case state of

(

1: nth.enabled = r_from.enabled = r_to.enabled = false

2: (

nth.enabled = true

r_from.enabled = r_to.enabled = false

)

3: nth.enabled = r_from.enabled = r_to.enabled = true

)

)

on s160 pressed do (rw.value=160; rh.value=120; aspect.value=1.0)

on s320 pressed do (rw.value=320; rh.value=240; aspect.value=1.0)

on s256 pressed do (rw.value=256; rh.value=243; aspect.value=1.266)

on s512 pressed do (rw.value=512; rh.value=486; aspect.value=1.266)

on s640 pressed do (rw.value=640; rh.value=480; aspect.value=1.0)

on s720 pressed do (rw.value=720; rh.value=486; aspect.value=0.9)

on conf_render pressed do (max render scene)

on go pressed do

(

local tempfilename_a = (getdir #image) + "\\ramplayertemp_a.avi"

local tempfilename_b = (getdir #image) + "\\ramplayertemp_b.avi"

if existfile tempfilename_b then

(

deletefile tempfilename_a

copyfile tempfilename_b tempfilename_a

tempfilename = tempfilename_b

)

else

(

if existfile tempfilename_a then

tempfilename = tempfilename_b

else

(

tempfilename = tempfilename_a

tempfilename_b = ""

)

)

case r_time.state of

(

1: render outputheight:rh.value outputwidth:rw.value \

pixelaspect:aspect.value \

outputfile:tempfilename vfb:off

2: render outputheight:rh.value outputwidth:rw.value \

pixelaspect:aspect.value \

outputfile:tempfilename vfb:off \

nthframe:nth.value framerange:#active

3: render outputheight:rh.value outputwidth:rw.value \

pixelaspect:aspect.value \

outputfile:tempfilename vfb:off \

nthframe:nth.value fromframe:r_from.value \

toframe:r_to.value

)

ramplayer tempfilename_a tempfilename_b

closerolloutfloater r_dialogue

) -- end of on go pressed

) -- end of rollout r_size

-- close the old rollout floater if it exists

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


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 Scripted Plug-ins. Here's a simple example:

Example:

tool foo

(

local b

on mousePoint clickno do

if clickno == 1 then b = box pos:worldPoint else #stop

on mouseMove clickno do b.pos = worldPoint

)

This tool allows the user to click in a viewport at which point a box is created. Dragging the mouse positions the box and releasing the mouse button stops the tool.

You'd start this tool by executing:

startTool foo

The syntax for tools is similar to that for utility definition constructs. They have local variables, functions, and event handlers, but tools have no user-interface items.

A tool is created using the tool definition construct in MAXScript. The top-level syntax is as follows:

tool <tool_name> [ prompt:<string> ] [ numPoints:<number> ]

( <tool_body> )

where <tool_name> is the name of an automatically created variable to hold the value that represents the tool. The scope of this variable is the current MAXScript scope. This value is also returned as a result of the tool declaration. The class of this value is MouseTool.

The optional prompt keyword argument specifies the prompt string displayed in the 3ds max Prompt Line while the tool is executing.

The optional numPoints keyword argument specifies the maximum number of points (mouse clicks) the tool will use. If the tool is still executing when you reach the numPoints number of mouse clicks, the tool will stop and return a value of #stop.

<tool_body> is enclosed in the required parentheses and is a sequence of clauses that define the functions and event handlers that process mouse clicks. These clauses are defined in detail in Mouse Tool Clauses.

The following method invokes a tool:

startTool <tool_name> [ prompt:<string> ] [ snap:#3D|#2D ] \

[ numPoints:<number> ]

where <tool_name> is the tool name used in a tool definition.

The optional prompt keyword argument specifies the prompt string displayed in the 3ds max Prompt Line while the tool is executing. If specified, this string overrides the prompt string specified in the tool definition.

The optional snap keyword argument specifies the upper limit on snapping. specifying a snap parameter does not turn on snap, only the user can turn it on in the interface. When 2.5D or 3D snapping is turned on by the user, the snap parameter restricts snapping to the specified level.

The optional numPoints keyword argument specifies the maximum number of points (mouse clicks) the tool will use. If specified, this value overrides the number of points specified in the tool definition.

The return value from startTool() will be either #stop if a called change handler returns the value #stop or the numPoints value is reached, or #abort if the user aborts the tool using a right-click or presses the ESC key.

A currently executing tool can also be aborted using the following method:

stopTool <tool_name>

where:

<tool_name> is the tool name used in a tool definition.

This method would typically be called in a callback function or change handler (see Change Handlers and Callbacks), or in a timer event handler in a rollout (see Timer).


Mouse Tool Clauses

The <tool_body> of a mouse tool definition is made up of a sequence of tool clauses as follows:

<tool_body> ::= { <tool_clause> }+

Tool clauses define the components of a tool and can be one of two basic things:

  • Local variables, functions or structure definitions are variables, functions, and structures whose scope is the tool. The <tool_body> is compiled in its own local scope and the locals are only visible inside the scope of the tool. Tool locals are heap-based locals, which are slightly different from normal (stack-based) locals. Normal locals are visible in the current scope and have a lifetime of one execution of that scope. Heap-based locals are also visible only in the current scope, but have a lifetime equal to the lifetime of the top-level expression where they are defined. A tool's locals are created the first time you execute the tool and are kept permanently in the heap (unless and until you redefine the tool). This means things like rollouts created in a tool that live beyond the simple execution of the tool can refer to these locals and the locals will still exist. Each time you execute a tool, its local variables are initialized to a value of undefined, or to their specified initialization value. For example, you can create a rollout in a tool, and the rollout's event handlers can access the locals defined in the tool because the rollout is executing within the scope of the tool. You cannot access the tool's locals from another utility or from Listener, because they are not executing within the scope of the tool. See Scope of Variables for more information.

  • Event handlers are special kinds of functions associated with particular events. Event handlers specify the processing you want to occur when a user clicks or moves a mouse, right-clicks, or starts or stops the tool. These actions generate named events and the optional event handler you supply for that event is called when the action occurs.

Formally, the syntax of a <tool_clause> is defined as follows:

<tool_clause> ::= <local_variable_decl> |

<local_function_decl> |

<local_struct_decl> |

<event_handler>

Locals

A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly the same as local variable, function, and structure definitions in MAXScript:

<local_variable_decl> ::= local <decl> { , <decl> }

<decl> ::= <name> [ = <expr> ] -- optional initial value

<local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr>

<local_struct_decl> ::= struct <name> ( <member> { , <member> } )

<member> ::= ( <name> [ = <expr> ] | <local_function_decl> )

Global variables cannot be declared as a tool clause, however they can be declared within event handler scripts. If you need to ensure a variable name references a global variable, declare the variable name as global immediately before defining the tool in your script.

When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. The reasons for this are described in Scope of Variables.

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.

gridPoint Point3

The current mouse position projected on the active grid in the coordinate system of the active grid. If the active grid is the home grid, the coordinate system is the home grid plane active in the current viewport (that is, the construction plane). See the discussion of grid versus world values below.

gridDist Point3

The distance in X, Y, and Z from the previous click point to the current click point in the coordinate system of the active grid. If the active grid is the home grid, the coordinate system is the home grid plane active in the current viewport (that is, the construction plane). See the discussion of grid versus world values below.

gridAngle Point3

The angles around the world X, Y, and Z axes from the previous click point to the current click point in the coordinate system of the active grid. If the active grid is the home grid, the coordinate system is the home grid plane active in the current viewport (that is, the construction plane). See the discussion of grid versus world values below.

shiftKey Boolean

true if SHIFT key was down.

ctrlKey Boolean

true if CTRL key was down.

altKey Boolean

true if ALT key was down.

lButton Boolean

true if left mouse button was down.

mButton Boolean

true if middle mouse button was down.

rButton Boolean

true if right mouse button was down.

When a create mouse tool is used in a level 5 scripted plug-in, an additional local variable is accessible:

nodeTM Matrix3

Provides read/write access to the transform of the node currently being created. This value is in the current grid coordinate system.

See Scripted Plug-ins for more information.

When writing SimpleObject scripted plug-ins, you should always use the gridPoint, gridDist, and gridAngle values rather than corresponding world values, as object-creation in SimpleObject scripted plug-ins is managed in the active grid coordinate system.

For gridDist, the .X and .Y components are the delta X and Y between the previous clicked point and the current mouse point in the plane of the current grid. The .Z component is a projection from the current Y screen coordinates onto a Z-vector (in the grid coordinate system) based at the last point clicked on the grid, such that the .Z value is the projected height up the Z-vector. For non-orthogonal viewports this is as expected, but for orthogonal viewports (in which you are always 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.

Example:

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

(

if p != undefined

then p.pos=worldPoint

else if lbutton do createPoint()

)

)

-- start the tool. No exit condition defined, so right-click to exit.

startTool PointCreator

Event Handlers

An <event_handler> is a special function definition local to a tool that you provide to handle the processing you want to occur when a user clicks in a viewport, right-clicks, or starts or stops the tool. Each user action generates a named event and any event handler you supply for that event is called when the action occurs. The available event handlers are:

on start do <expr>

Called when the tool starts.

on end do <expr>

Called when the tool ends.

on freeMove do <expr>

Called when the mouse moves prior to the first click.

on mousePoint <arg> do <expr>

Called for each mouse click, parameter arg contains the number of the click.

on mouseMove <arg> do <expr>

Called when the mouse moves anytime after the first click.

on mouseAbort <arg> do <expr>

Called when the user right-clicks to cancel or presses the ESC key.

The <arg> parameter on each of the mouse event handlers lets you know which mouse click you are in. Mouse clicks are actually only the mouse click release, except for the initial mouse click. If you do a mouse click, drag, release, move, click, drag, and release, the on mousePoint event handler is called three times: the first click, the first release, and the second release, with <arg> values of 1, 2, and 3, respectively. The mouse click counter is incremented after processing the on mousePoint event handler, so the <arg> parameter for the mouseMove and mouseAbort event handlers specify the click count for the next mouse click. In the previous example, when you drag between the first click and first release, the <arg> value for a mouseMove event handler will have a value of 2. During the following move, click, and drag it will have a value of 3.

The following script simply demonstrates when the various event handlers are called. Simply run this script and drag in the viewports. Right-click or press the ESC key to stop the tool's execution.

Example:

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

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.

Example:

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

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


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.

A parameter block can be associated with a rollout in the scripted plug-in that provides a user interface for the parameters in the parameter block. When associated in this way, the parameters are "wired" to their spinners and checkboxes, etc., and both update automatically as the other changes.

The general form for a scripted plug-in is:

plugin <superclass> <varname> {keyword:val}

( <plugin_body> )

where:

<superclass> is one of the currently-supported plug-in superclasses:

Geometry

SimpleObject

Shape

Light

Helper

Modifier

SimpleMod

Material

TextureMap

RenderEffect

Atmospheric

<varname> is the name that will be given to the global variable that contains this plug-in class. This class value is just like a normal plug-in class (like box, sphere, etc.) and you can create an instance of the plug-in in MAXScript by applying the class value.

{keyword:val} is an optional sequence of keyword/value pairs defining options for the plug-in. These pairs are:

name:<string>

The optional name: parameter specifies the name of the plug-in as seen in the 3ds max user-interface. For example, if the superclass of the plug-in is geometry or light, this name would be displayed on the plug-in's button in the Create panel; if the superclass of the plug-in is modifier, this name would be displayed on the plug-in's button in the Modify panel; and if the superclass of the plug-in is material or textureMap, this name would be displayed in the Material/Map Browser. The default name is the plug-in's <varname>.

category:<string>

The optional category: parameter specifies in which object category (access via the object category list) the plug-in will appear in. This parameter is applicable only to plug-ins that appear in the Create panel. The default category in "Standard". Note that there is a fixed number of buttons available in the Create panel for each category. If a button for your plug-in does not show up in the appropriate Create panel, you may need to make a new category for it.

classID:#(<integer>,<integer>)

You supply the classID:#(<integer>,<integer>) parameter if you want the plug-in to be creatable and storable in the scene. This ID becomes the permanent ID for the class and is used by 3ds max to identify objects as they are saved and loaded in the scene. You don't need to supply a class ID value if the plug-in is to be like a System object that only creates other types of objects in the scene. The class ID is basically a pair of numbers, chosen randomly so that (hopefully) they won't conflict with another plug-in. MAXScript provides a method to generate a fresh random class ID each time you run it:

genClassID()

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

extends:<maxClass>

The extends:<maxClass> parameter is supplied if you want to base your plug-in on an existing plug-in. This basically lets you add a new class that works internally exactly like the one you are extending, but with an expanded or replaced user interface. The class you specify must have the same superclass as specified in the scripted plug-in header. Current limitations prevent certain plug-ins from being extended, in particular those with custom creation managers. These include target lights and cameras and all the System plug-ins. You can tell if a plug-in is not extendable if your new rollouts do not appear.

When you create an object of scripted plug-in that extends another, MAXScript also creates an internal object of the extends: plug-in and passes most of 3ds max's interaction with your plug-in onto the internal object. This is called delegation and the internal extends: plug-in object is the delegate. The delegate is visible in your plug-in's objects in Track View and you can access the delegate in your scripts to control it as needed. See the locals section below for more information. The delegate is not shown in TV if replaceUI:true is specified.

replaceUI:<boolean>

The replaceUI: parameter is used only when extends: is supplied to indicate whether the rollouts in your plug-in should add-to or replace the extended plug-ins rollouts. The default is false, which means your rollouts will be appended at the end of the extended plug-in's. Another current limitation when extending plug-ins whose objects are created in the Create panel only allows user interface replacement in the Modifier panel; the original plug-in's rollouts are always displayed along with the scripted rollouts in the Create panel.

version:<integer>

The optional version: parameter specifies the version number of the scripted plug-in. The value assigned to this parameter is used when updating the scripted plug-in definition. The default value for this parameter is 1. See Updating Scripted Plug-ins for more information on this parameter.

invisible:<boolean>

The optional invisible: parameter gives control over whether the plug-in is visible in the Create panel Object Type rollout or in the Material/Map Browser, etc. This is useful for component or controlling objects created as part of a group, say in a System-style plug-in that should not be creatable on their own. Set this parameter to true to hide the plug-in.

silentErrors:<boolean>

The optional silentErrors: parameter gives control over whether MAXScript run-time error messages are displayed when executing handlers in the scripted plug-in. If this parameter is set to true, error messages will not be displayed. This may be useful for distributed scripted plug-ins that may confuse the user with MAXScript error messages.

<plugin_body> is enclosed in the required parentheses and is a sequence of clauses that define the local variables and functions, parameters, user-interface items, and event handlers that define the plug-in. These clauses are defined in detail in Scripted Plug-in Clauses.

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


Scripted Plug-in Clauses

The various optional clauses inside the plug-in body are similar to those for scripted utilities and tools. There is an additional scripted plug-in specific clause <parameters> for defining scene-savable and Track View visible parameters for the plug-in.

The <plugin_body> of a scripted plug-in definition is made up of a sequence of plug-in clauses as follows:

<plugin_body> ::= { <plugin_clause> }+

Plug-in clauses define the components of a scripted plug-in and can be one of five basic things:

  • Local variables, functions or structure definitions are variables, functions, and structures whose scope is the plug-in. These locals will exist as long as the instance of the plug-in exists. The visibility of locals, and accessing scripted plug-in locals from external code, are described in Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code and Accessing Locals and Other Items in a Rollout from External Code .

  • 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 Scripted Mouse Tools.

  • 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 Utility Clauses.

  • Event handlers are special kinds of functions associated with particular events. Event handlers specify the processing you want to occur when a user creates an instance of the scripted plug-in or when 3ds max calls the scripted plug-in. These actions generate named events and the optional event handler you supply for that event is called when the action occurs.

Formally, the syntax of a <plugin_clause> is defined as follows:

<plugin_clause> ::= <local_variable_decl> |

<local_function_decl> |

<local_struct_decl> |

<parameters> |

<tools> |

<rollouts> |

<event_handler>

Locals

A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly the same as local variable, function, and structure definitions in MAXScript:

<local_variable_decl> ::= local <decl> { , <decl> }

<decl> ::= <name> [ = <expr> ] -- optional initial value

<local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr>

<local_struct_decl> ::= struct <name> ( <member> { , <member> } )

<member> ::= ( <name> [ = <expr> ] | <local_function_decl> )

Global variables cannot be declared as a plug-in clause, however they can be declared within event handler scripts. If you need to ensure a variable name references a global variable, declare the variable name as global immediately before defining the plug-in in your script.

When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. The reasons for this are described in Scope of Variables.

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.

The version local variable contains the version number specified in the scripted plug-in definition. See Updating Scripted Plug-ins for more information on this variable.

The this local variable always contains the MAXScript value corresponding to the current instance of the scripted plug-in. This variable provides a guaranteed way of accessing parameters on the new object within plug-in code (in case there are locals or globals with the same name), and it is a way of referencing the plug-in in case you want to store it to a variable.

The delegate local variable contains the MAXScript value corresponding to the instance of the plug-in being extended. To access common properties or subAnim properties in the instance of the plug-in being extended, you need to do so via the delegate local variable. For example,

delegate.width = thisWidth

inside a plug-in function or handler would set the .width property in the instance of the plug-in being extended. The delegate local variable in a scripted plug-in that creates a scene object does not contain the node itself, but a the BaseObject of that node. As such, you can not access the node level properties of the object being created. An exception to this is the node's transform, which is exposed to the scripted plug-in through a local variable called nodeTM. This variable is described in the applicable scripted plug-in type topics.

If the extends: parameter is not supplied for a plug-in, delegate returns undefined.

As well as local variables, you can define local functions and local structures, just as you can with scripted utilities and rollouts.

Parameters

You can define one or more parameter blocks in a scripted plug-in. A parameter block has the form:

parameters <name> [type:#class] [rollout:<name>]

(

{ <param_defs> }+

{ <event_handler> }

)

A parameter block defines a set of parameters for the plug-in, which are like plug-in local variables, but are directly animatable and are saved to and restored from scene files. You can also associate each parameter with appropriate user-interface elements in one of the plug-ins rollouts. When associated in this way, the parameters are "wired" to their spinners and checkboxes, etc., and both update automatically as the other changes, so you don't have to write any user-interface event handlers for them. These parameters correspond to the visible parameters you see in other 3ds max plug-ins. Parameters in the parameter block do not participate in 3ds max's undo system, therefore changes to the parameter values are not undoable.

The <name> you give to a parameter block becomes permanently associated with the parameter block and is used by MAXScript to connect to the right parameter block in a plug-in object that is being loaded from a scene file. This becomes important as you modify a plug-in script and yet there are still objects corresponding to the old definition in other files. When the old-version object is loaded, MAXScript attempts to convert it to the new definition, using the current parameter block definition as a guide. In order to properly do this, each parameter in a parameter block is also given a permanent name. So, if you have existing objects of your plug-in in other files, don't go randomly changing parameter block names or they won't be loadable.

The optional type:#class specifies that the parameters in the parameter block are "class" parameters. This means that there is one copy of each parameter for the *all* the objects of this plug-in class; they all share the parameter. Examples of existing class parameters are the creation type and type-in parameters in a typical geometry primitive.

The optional rollout:<name> specifies a rollout definition elsewhere in the plug-in body to use as the user-interface rollout for the parameter block's parameters. A limitation of the internal parameter block mechanism requires that each parameter block be associated with a separate rollout and each rollout be associated with only one parameter block. This means that each rollout you want to have in the plug-ins user interface must have its own separate parameter block.

The <param_defs> are definitions for each parameter in the parameter block. They have the form:

<name> type:<#name> [tabSize:<integer>] [tabSizeVariable:<boolean>] \

[default:<operand>] [animatable:<boolean>] \

[subAnim:<boolean>] [ui:<ui_def>]

The <name> is permanently associated with the parameter in the same sense as parameter block names. They are used to connect to the right parameter when loading objects of the scripted plug-in and allow you to make certain changes to a script and yet still be able to load old version objects. So, as with parameter block names, don't change or re-use parameter names if you have scene files with old version objects you want to get at.

The type:<#name> parameter is required and defines the parameter type. It can be one of the following:

#float animatable

#integer animatable

#color animatable

#point3 animatable

#boolean animatable

#angle animatable

#percent animatable

#worldUnits animatable

#string

#filename

#colorChannel animatable

#time animatable

#radiobtnIndex

#material

#texturemap

#bitmap

#node

#maxObject

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.

The various xxTab parameter types allow you to store an array of values having the corresponding type. The initial size of the array is specified using the tabSize: specifier. If tabSizeVariable:true is specified, the size of the array will be automatically expanded when you assign to an higher array index. For example:

parameters main rollout:params

(

mapAmounts type:#floatTab tabSize:4 tabSizeVariable:true \ ui:(map1Amount, map2Amount, map3Amount)

)

defines an array parameter containing 4 float elements (defined by the tabSize: parameter). You can associate a separate rollout element with each array parameter element. These parameters appear as arrays when accessed in plug-in handler code, for example:

a = mapAmounts[i]

Since tabSizeVariable:true was specified, the following will automatically increase the array size to 10:

mapAmounts[10] = a

You can also increase or decrease the array size by assigning a value to the .count property

Each element in an array parameter whose base type is a number of some kind (floatTab, intTab, percentTab, etc.) is independently and automatically animatable, unless you specify animatable:false. You can get at and assign individual controllers via the .controller property. For example:

c = mapAmounts[i].controller

The optional parameter default:<operand> specifies a initial default value for the parameter. The <operand> expression has to be convertible by MAXScript to the base type of the parameter.

The optional parameter animatable:<boolean> specifies whether the parameter is animatable and hence visible in the track view. Only those base types marked as animatable in the above type list can be specified as animatable. Defaults to true.

The optional parameter subAnim:<boolean> can be specified for the 3ds max object types: #node, #material, #textureMap, and #maxObject. If specified as true, the 3ds max object is made visible as a sub-object track in track view. Defaults to false.

The optional parameter ui:<ui_def> is used to specify which user-interface element in the parameter block's associated rollout is to be linked to this parameter. When so linked, the handling of user actions for these elements are automatic and they also update automatically to follow any changes to the parameter caused by animation, scripts, etc. For example, in the following, the parameter block named main is associated with the rollout named params. The parameters height and spread are then linked with the spinners named height and spread in that rollout:

parameters main rollout:params

(

type:#node subAnim:true

fill type:#node subAnim:true

back type:#node subAnim:true

height type:#float animatable:true default:10 ui:height

spread type:#float animatable:true default:10 ui:spread

on height set val do

(

key.pos.z = val

back.pos.z = val * 1.5

fill.pos.z = val * 0.5

)

)

rollout params "Light Parameters"

(

spinner height "Height"

spinner spread "Spread"

)

Once this is done, the parameter and spinner are linked, such that changes in one are reflected immediately and automatically in the other. Further, if the parameter is animated, the spinner will show red keyframe highlights when the time slider is positioned at a keyframe for that parameter, as with other 3ds max plug-ins. The kinds of user-interface items that can be linked to particular parameter types is limited to the following sensible combinations:

Parameter type Rollout user-interface item

#integer spinner, slider, radioButtons, checkbox, checkbutton

#float spinner, slider

#time spinner, slider

#color colorpicker

#angle spinner, slider

#percent spinner, slider

#colorChannel spinner, slider

#boolean checkbox, checkbutton

#node pickButton

#textureMap mapButton

#material materialButton

#worldUnits spinner, slider

Parameter Event Handlers

Two event handlers are associated with parameters. These handlers are called when a parameter is assigned a value, or when the parameter value is retrieved.

on <name> set <arg> do <expr>

A set handler can be supplied for any of the parameters in the block and it will be called whenever the parameter is updated, either through an associated rollout user-interface item or directly, especially via MAXScript property assignment. In general, the way you would code change handlers is to supply set handlers for parameters, rather than on <item> change handlers for spinners and checkboxes, etc. in the rollout definition. A set handler in used in the previous example to update the light positions when the height parameter value changes.

The set handlers are also called when an instance is created or loaded so that common dependent actions can be taken, such as setting up other dependent system object or delegate properties.

If a parameter is animated and has a set handler supplied, the handler will be called whenever the 3ds max time changes, say by dragging the time slider around or within an animation rendering.

on <name> get <arg> do <expr>

A get handler can be supplied for any of the parameters in the block and it will be called whenever the parameter value is retrieved. This will occur when the user interface updates itself, a script accesses the parameter, a viewport is redraw, a render occurs. In all these cases, the animated value is retrieved one or more times. The get handler is called with a single argument which is the current value stored in the paramblock (or underlying controller if the parameter is animated). The currentTime variable is set to the time at which the value is being retrieved and not necessarily the current slider time, since you can ask a parameter for its value for any specified time. If you implement the get handler, you must return a value, and that value is returned as the value of the parameter to the value requester. If you don't want to modify the value, but just monitor accesses, return the argument. You can also compute and return any value of the appropriate type.

Tools

Plug-ins can define local mouse tools. Although you can have any number of local tools and start them as needed, you would typically supply a single tool with the reserved name create. This is taken to be the create tool for objects created in the Create panel and is invoked automatically when you create scripted plug-in objects. Tool definitions are described in Scripted Mouse Tools.

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

Note that rollout local variables only live as long as the rollout is open in the user interface. It gets opened and closed each time it is displayed and so the rollout open and close events are signalled at this time. If you want to load any spinners or other user-interface elements from the currently editing plug-in object, supply an on <rollout> open event handler to pick up these values. Rollout definitions are described in Utility Clauses.

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


Scripted Plug-in Methods

The addPluginRollouts() is used within scripted plug-in create tools, specifically for level 1 plug-ins that don't create instances of themselves in the scene but might create other objects within their create tool. This method lets you install rollouts for a specified object in the Create panel, typically one of the objects being created in the create tool, so that its parameters can be adjusted directly during creation. The form is:

addPluginRollouts <obj>

In the following example, a variation of the three light mouse tool example presented in Mouse Tool Clauses 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.

Example:

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

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

)

)

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


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.

You can specify an update event handler in a scripted plug-in and it will be called whenever the object is updated by this schema migration mechanism. To make this more useful, MAXScript supports a version number on scripted plug-ins. The version for any particular instance of the plug-in can be accessed via the version special local variable in any plug-in local function or handler. When the update event handler is called during a schema-migration, the old version number is still in force, but is updated to the current version number immediately after update. For example:

plugin helper lightMaster

name:"Light Master"

classID:#(12345,54321)

extends:Dummy

invisible:true

replaceUI:true

version:3 -- set current version to 3

(

parameters main rollout:params

...

on update do

(

if version == 1 then ... -- do something special for v1 instances

)

...

)

Note that you only need to use this explicit version access and update scheme if you want to do some special manual conversion over-and-above the automatic migration described above.

Finally, if there are no existing instances of the plug-in, either in the current scene or in other scenes that you care about keeping, you can simply delete them and make whatever changes you like the scripted plug-in definition. The above version update considerations come into play only when you wish to support old version objects of your scripted plug-in.

See also

Scripted Plug-ins


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.

Example:

plugin geometry foo_plugin_def

name:"FooBar"

category:"Scripted Primitives"

(

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:

Example:

plugin geometry Cuboid

name:"Cuboid"

classID:#(0x133067, 0x54374)

category:"Scripted Primitives"

extends:Box

(

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

delegate.width = delegate.length =

delegate.height = 2 * fmax (abs gridDist.x) (abs gridDist.y)

)

)

See also

Updating Scripted Plug-ins

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse Tools


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 Editable Mesh.

Example:

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

)

params "Two Faces Parameters"

(

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.

There are three additional event handlers that may be implemented for a scripted SimpleObject:

on OKtoDisplay do <boolean_expr>

If the OKtoDisplay event handler is implemented, <boolean_expr> should return true or false depending on whether it is OK to display the current mesh. This is useful in situations where a mesh might be in some degenerate state for particular parameter settings and so should not be displayed in the viewports. The default implementation is true. Note, empty meshes are OK to display.

on hasUVW do <boolean_expr>

If the hasUVW event handler is implemented, <boolean_expr> should return true or false depending on whether UVW coordinates are present on the mesh. In many primitive objects, a Generate Mapping Coords checkbox is provided for the user to control UVW coordinate generation and the hasUVW handler expression would return the state of this checkbox. The default implementation returns true or false depending on whether the mesh has texture vertices present or not. At present, only a single map channel is supported.

on setGenUVW <onOff> do <expr>

The setGenUVW event handler is called when 3ds max wants the plug-in to automatically generate mapping coordinates, as happens when you first render an object that has a material applied, but not mapping coordinates. It is called with a switch argument <onOff> which is true or false to turn on or off the mapping coordinates. If your plug-in is managing mapping coordinates, it should implement this handler and generate mapping coordinates when called with a true argument. For example:

on setGenUVW onOff do

(

genMapCoords = onOff

if genMapCoords and gen_mapping_coords()

)

where gen_mapping_coords() is a function that applies mapping coordinates to the mesh, returning true if the mapping was successful, false if not.

Here's another example that creates a mesh by first building other temporary objects and using mesh booleans to build the final mesh:

Example:

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

)

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.

See also

Updating Scripted Plug-ins

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse Tools


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.

Example:

plugin shape Extended_Rect

name:"Rectangle2"

classID:#(0x133067, 0x54375)

extends:rectangle version:1

category:"Splines"

(

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

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse Tools


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 Scripted Plug-in Methods.

See also

Updating Scripted Plug-ins

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse Tools


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 Scripted Plug-in Methods.

See also

Updating Scripted Plug-ins

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse 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.

Example:

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: "

)

)

Example:

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

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse Tools


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.

Example:

plugin simpleMod saddle

name:"SaddleDeform"

classID:#(685325,452281)

version:1

(

parameters main rollout:params

(

amount type:#integer ui:amtSpin default:20

)

rollout params "Saddle Parameters"

(

spinner amtSpin "Amount: " type:#integer range:[0,1000,20]

)

on map i p do

(

p.z += amount * sin((p.x * 22.5/extent.x) * (p.y * 22.5/extent.y)

p

)

)

This script defines a new SimpleMod plug-in named SaddleDeform. It applies a saddle-type deformation to an object, curving up 2 opposite corners and curving down the other two opposite corners (try it on a plane object to see this best). There is a single parameter spinner, amount that specifies how much deformation to apply. The key component of a SimpleMod plug-in is the map handler. Its form is:

on map <index> <point> do <expr>

This event handler is called once for every point in the object (or current point selection in the object) being modified. These points may be mesh vertices, spline vertices, NURBS CVs, and so on. The <index> argument gives the number of the point, but this index may not correspond to a vertex number in a mesh or a spline. The <point> argument supplied to the map handler gives the current object-space coordinates of the point as a Point3. The function should modify the supplied point value as appropriate and return it as the result of the map handler call. In the example above, the map handler applies a Z-coordinate deformation, using the equation z = sin(x * y), so that all the points retain their X and Y coordinates and the Z is moved up or down so as to follow the saddle function. Note that all coordinates are object-local.

The <index> value is 1-based, however the scripted plug-in is called with a <index> value of 0 to signal that this particular map call is being used by the gizmo bounding box drawing code to compute points in the gizmo box to draw. This occurs hit testing is performed on the object the SimpleMod modifier is applied to and the gizmo bounding box is displayed. This will be the case if the object is selected, the Modifier panel is active, and the SimpleMod modifier is selected in the object's modifier stack.

It is basically up to the object being modified to decide what index value to pass. For meshes, for example, it is the actual mesh vertex index. For patches, it is the control points first all in one sequence, followed by the in and out vectors for each control point in control point order. For splines, it is control point, in vector, out vector in control point sequence within the curve sequence. This ordering may change in future versions of 3ds max.

Since the map handler can be called many times, even on simple objects, it is highly recommended that you minimize the number of values that are created in the map handler. This will reduce the need for garbage collection to be run. If you need several local variables in the map handler, it is recommended that you declare one or more Point2 or Point3 values in the scripted plug-in definition, and then store values to the component values of the Point2 or Point3 values. This will prevent new local variables from being allocated in the map handler.

You should not try to access the object being modified from within the map handler as this will attempt to evaluate the scripted modifier again. This will result in an infinite loop and hang 3ds max.

There are also three pre-defined plug-in locals you can access in the map handler, as follows:

min -- the modifier context's bounding box min coordinate

max -- the modifier context's bounding box max coordinate

center -- the modifier context's bounding box center coordinate

extent -- the modifier context's bounding box extent or size

In the example above, the map handler use the extent pre-defined local variable to compute a scaling for the saddle function, so that it gets a 1/8th cycle of the function (22.5 degrees) across the whole object. These bounding box locals relate to the modifier's context, either the whole object or group of objects if applied to a scene node selection, or sub-object selection if there is a sub-object selection modifier below it on the stack (such as a Mesh Select).

You can also use some other built-in capabilities of SimpleMod to implement modifier limits as in Bend and Taper. To do this, implement handlers for the following (you must implement all if you implement any):

on modLimitZMin do <expr>

on modLimitZMax do <expr>

on modLimitAxis do <expr>

If called, the on modLimitZMin and on modLimitZMax handler expressions must evaluate to float values corresponding to the minimum and maximum limits and the on modLimitAxis handler expression must return #x, #y or #z to specify the limit axis. The MAXScript global variable currentTime contains the time at which these values should be computed, although, normally, simple access to parameter values will yield the correct currentTime value automatically. The simplest way to implement these handlers is to maintain limit parameters and associated spinners and checkboxes, and simply pass these parameter values back.

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

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse Tools


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.

Example:

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

(

-- setup initial material

delegate.opacityFalloff = 75

)

)

See also

Updating Scripted Plug-ins

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse Tools


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

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse Tools


Scripted RenderEffect Plug-ins

A scriptable RenderEffect plug-in can be declared by specifying the <superclass> as RenderEffect and by declaring an apply event handler. When declared, the render effect can be seen in Render Effects > Add dialog.

on apply <bitmap> do <expr>

When the scripted effect is added as one of the rendering effects and "Update Scene" or "Update Effect" buttons are pressed, the apply event handler is called and passed a bitmap which can be modified with any changes the render effect wants to make. The bitmap you are given is the current rendered image that has had all of the prior effects in the render effects list applied to it. You modify this bitmap in place, typically by using the getPixel() and setPixel() functions. This modified bitmap is then passed onto the next render effect in the list or to the render output if it is the last effect.

To allow scripted Effects to take advantage of the g-buffer channel access, the following handlers are present:

on channelsRequired do <expr>

The handler expression must evaluate to an array of the g-buffer channel names that are required. The g-buffer channel names are:

#zDepth

#matID

#objectID

#UVCoords

#normal

#unClamped

#coverage

#node

#shaderColor

#shaderTransparency

#velocity

#weight

on preApply <bitmap> do <expr>

The preApply handler allows the scripted effect to analyze the incoming render bitmap and its channels in order to precondition the delegate's effect processing.

So, you might add an on channelsRequired do to add #node and #coverage channels to the renderer's bitmap, and an on preApply bm do to get the #node channel out as a mask and then set it into a delegate's mask parameter to limit an effect to a given object.

You cannot call render() in a scriptable RenderEffect plug-in, as this would cause the RenderEffect to be recursively called.

Here's a simple example that extends the Blur effect to add another rollout that has a node picker button. If you pick a node it generates a channel mask and uses that to limit the blur to that object:

Example:

plugin RenderEffect myBlurFX

name:"Super Blur FX"

classID:#(6545,456581)

extends:Blur

version:1

(

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

)

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

)

)

Example:

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]

)

)

Example:

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

(

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

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse Tools


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.

Example:

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

Scripted Plug-in Methods

Scripted Plug-in Clauses

Scripted Plug-ins

Scripted Mouse Tools


Command Panels

The following methods are used to get or set which command panel is active:

setCommandPanelTaskMode mode:<panel_name>

Sets the specified command panel as active. The valid panel_name values are:

#create -- Create Panel

#modify -- Modify Panel

#hierarchy -- Hierarchy Panel

#motion -- Motion Panel

#display -- Display Panel

#utility -- Utility Panel

getCommandPanelTaskMode()

Returns the current command panel as a name value. The name values correspond to the panel_name values for SetCommandPanelTaskMode().

The following 3ds max system global variables are associated with the command panel:

cui.commandPanelOpen

Lets you get and set whether the command panel is displayed. A Boolean value - true if the command panel is displayed, false if not displayed.

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

Modify Panel


Create Panel

The startObjectCreation() method is used to simulate the user finding a Create Panel button for a given object class and pressing that button, putting 3ds max into create mode for that object class. The form is:

startObjectCreation <scene_object_class>

For example:

startObjectCreation box

startObjectCreation targetSpot

This method simply opens up the Create Panel at the right tab and category and depresses the appropriate object button.

This method is primarily intended for use in macroScripts, but can be used in generalized scripts. Script execution will continue immediately after entering the create mode, and you must ensure that the script does not interfere with the object creation.


Modify Panel

The following methods are associated with the Modify panel:

enableShowEndRes <boolean>

If the boolean parameter is true, allows the Show End Result On/Off Toggle icon to remain pressed in. If false, the Show End Result On/Off Toggle icon will return to the off state after being pressed. This method must be used in true/false pairs, as its effect is "sticky" when selecting other objects or modifiers, or when switching away from and back to the Modify panel.

IsSubSelEnabled()

Returns true if the user is allowed to enter Sub-Object mode, false otherwise.

enableSubObjSel <boolean>

If the boolean parameter is true, allows the user to enter Sub-Object mode for those objects/modifiers that have Sub-Object modes defined. If false, the Sub-Object button is disabled. This method must be used in true/false pairs, as its effect is "sticky" when selecting other objects or modifiers, or when switching away from and back to the Modify panel.

modPanel.addModToSelection <modifier>

Applies a modifier to the current selection opened in the Modify panel. It should be used in place of addModifier() in places where the target is a selection or group or where you have the stack open at a particular place in the Modify panel with a sub-object selection active and you want the modifier applied to that selection. addModifier() adds the modifier separately to each object in the selection or group and does not honor the current active sub-object selection in all cases. The Modify panel must be open on the selection you want to apply the modifier to, otherwise the function does nothing.

modPanel.getCurrentObject()

Returns the modifier or base object currently selected in the Modify panel stack. If the Modify panel is not open, this function returns undefined.

modPanel.getModifierIndex <node> <modifier>

Returns the index of the given modifier in the modifier stack for the given node. This index corresponds to the modifiers position in the <node>.modifiers array. This function returns undefined if the given modifier is not in the node's modifier stack.

modPanel.setCurrentObject < modifier | node | node_baseobject >

Sets the specified object in the current modifier stack to be the active object in the modifier stack. The Modify panel must be open on the object containing the modifier or base object to be selected, otherwise the function does nothing.

Examples:

modPanel.addModToSelection (bend()) -- apply bend modifier to current selection

modPanel.getModifierIndex $ foo -- returns index of modifier foo

modPanel.setCurrentObject $ -- open on base object

modPanel.setCurrentObject $.baseObject -- same as above

modPanel.setCurrentObject $.taper -- open on taper modifier in object

modPanel.setCurrentObject $.modifiers[3] -- open on 3rd modifier

modPanel.setCurrentObject foo -- open on foo object or modifier

The following 3ds max system global variables are associated with the Modify panel:

numSubObjectLevels

Lets you get the number of sub-object levels supported by the object or modifier currently selected in the modifier stack. If the Modify panel is not open or no objects are selected, the global contains the value undefined.

subObjectLevel

Lets you get and set the sub-object level in the Modify panel if it is open. An Integer value of zero or greater up to the number of sub-object levels supported by the currently open modifier, typically in the order shown in the Sub-Object drop-down list. A subObjectLevel of 0 means sub-object mode is off. If the Modify panel is not open or sub-object level setting not permitted in the current modifier, the global contains the value undefined. For example:

b=box() -- create a box

em=edit_mesh() -- create an Edit Mesh modifier

addModifier $box01 em -- add edit mesh mod

max modify mode -- open mod panel

select $box01 -- select object box01

print subObjectLevel -- print the current subobject level

subObjectLevel = 2 -- set sub-object level to Edge

showEndResult

Lets you get and set the state of the Show End Result Toggle icon in the Modify panel. A Boolean Value – true if Show End Result is on, false if off.


Main Toolbar

The following methods are associated with 3ds max's main toolbar:

enableUndo <boolean>

Enables or disables the Undo icon.

hitByNameDlg()

Opens the standard 3ds max Select By Name dialog allowing users to select objects. Returns false if the user cancels out of the Select by Name dialog, true otherwise.

toolMode.uniformScale()

Set scale mode to Uniform Scale.

toolMode.nonUniformScale()

Set scale mode to Non-uniform Scale.

toolMode.squashScale()

Set scale mode to Squash.

enableRefCoordSys <boolean>

Enables or disables the Reference Coordinate System drop-down list.

toolMode.coordsys <mode_name>

Sets the Reference Coordinate System. Valid <mode_name> values are:

#view

#screen

#world

#parent

#local

#grid

getRefCoordSys()

setRefCoordSys <mode_name>

Get and set the Reference Coordinate System. Valid <mode_name> values are:

#hybrid -- View

#screen -- Screen

#world -- World

#parent -- Parent

#local -- Local

#object -- Pick object or Grid – not valid for setRefCoordSys()

enableCoordCenter <boolean>

Enables or disables the Coordinate System Center icon.

getCoordCenter()

setCoordCenter <name>

Get and set the Coordinate System Center. Valid <name> values are:

#local -- Use Pivot Point Center

#selection -- Use Selection Center

#system -- Use Transform Coordinate Center

toolMode.transformCenter()

Sets Coordinate System Center to Transform Coordinate System.

toolMode.selectionCenter()

Sets Coordinate System Center to Selection Center.

toolMode.pivotCenter()

Sets Coordinate System Center to Pivot Point Center.

getNumAxis()

This method reflects the Coordinate System Center state. If it is set to Pivot Point Center then this method returns #individual otherwise #all.

setToolBtnState <name> <boolean>

Set the specified tool buttons on or off. This method does not put into the mode, it just changes the state of the tool button. This method does not change the state of any button other than the specified button. The valid <name> values are:

#move -- Move button on/off

#rotate -- Rotate button on/off

#nuscale -- Scale button on/off – doesn't change scale type

#uscale -- Scale button on/off – doesn't change scale type

#squash -- Scale button on/off – doesn't change scale type

#select -- Select button on/off

getToolbtnState <name>

Returns whether the specified tool button is on or off as a <boolean> value. Valid name values are:

#select

#move

#rotate

#uscale -- returns true if any of the scale button states is on

#nuscale -- returns true if any of the scale button states is on

#squash -- returns true if any of the scale button states is on

The following methods deal with the Named Selection Set drop-down list. These methods are not intended for casual usage.

clearCurSelSet()

Clears the edit field of the Named Selection Set drop-down list. Does not deselect the currently selected objects.

clearSubSelSets()

Clears the named selections from the Named Selection Set drop-down list. The named selection sets still exist, they just don't show in the drop-down list. This command can be dangerous to use unless you are in Sub-Object mode in the Modify panel, as there is not a direct method to rebuild the Named Selection Set list. When in Sub-Object mode in the Modify panel, the namedSelSetListChanged() method will rebuild the list.

namedSelSetListChanged()

When in Sub-Object mode in the Modify panel, this method will rebuild the named selection set list.

setCurNamedSelSet <string>

Sets the edit field of the Named Selection Set drop-down list to the specified string. This method not change the current selection set or add the specified string to the named selection set list.

appendSubSelSet <string>

Appends the specified string to the Named Selection Set drop-down list. This method not change the current selection set. Modifiers in 3ds max use this method to add sub-object named selection sets to the Named Selection Set drop-down list. This is done whenever the selection level changes.

The following 3ds max system global variables are associated with the main toolbar:

preferences.constantReferenceSystem

Lets you get and set whether to use a constant Reference System for the Move, Rotate, and Scale tools. A Boolean value - true if Constant is on, false if off. This variable matches the Constant check box in Customize menu > Preferences > General > Reference Coordinate System.

toolmode.commandmode

Get/set the 3ds max command mode. The return value when getting the command mode is a <name> value if the command mode is a recognized command mode, otherwise the return value is an integer value. The recognized command modes are:

#SELECT

#MOVE

#ROTATE

#NUSCALE

#USCALE

#SQUASH

#VIEWPORT

#HIERARCHY

#CREATE

#MODIFY

#MOTION

#ANIMATION

#CAMERA

#NULL

#DISPLAY

#SPOTLIGHT

#PICK

When setting the 3ds max command mode, only the following command modes are valid:

#SELECT

#MOVE

#ROTATE

#NUSCALE

#USCALE

#SQUASH

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

Coordinate Display

Progress Bar Display

Status Bar Buttons


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.


Coordinate Display

The following methods are associated with 3ds max's Status Bar Coordinate Display:

disableStatusXYZ()

Disables mouse tracking and display of coordinates to the X, Y, Z status boxes.

enableStatusXYZ()

Enables mouse tracking and display of coordinates to the X, Y, Z status boxes.

setStatusXYZ <format_name> <point3>

Displays the component values of the Point3 value in the X, Y, Z status boxes. The format of the displayed values is controlled by format_name. The valid format_name types are:

#universe

display point3 as position in current units

#scale

display point3 as percentages – a point3 component value of 1 displays as 100%

#angle

display point3 as angles – point3 component values are in radians

#other

display point3 as straight floating point values.

Note: Using a <format_name> value of #other for setStatusXYZ() does not correctly display the specified point3 value. The X and Y component values are displayed in the Y and Z status boxes, and the X status box is blank.


Progress Bar Display

This group of functions let you display a progress bar for operations that may be time consuming, similar to the progress bar 3ds max uses for IK, Preview Rendering and Reduce Key computations. The functions are:

progressStart "caption"

Initially displays the progress bar with the caption given.

progressUpdate <percent>

Updates the bar display to show the given percentage complete (in the range 0-100). This function also checks to see if the user has clicked the Cancel button in the progress bar and returns true if the computation should continue and false if the user has requested a cancel. You can also call getProgressCancel(), described below, to check the cancel status, which is a low overhead function and so may be called more frequently than progressUpdate().

progressEnd()

Signals the end of the operation and removes the progress bar display.

getProgressCancel()

A low-overhead function that checks whether the user has canceled the operation via the Cancel button in the progress bar. You may want to call this function frequently within deep loops in your code to reduce cancel latency for the user, because you should only call progressUpdate() as needed to show significant progress bar changes to keep overhead low. The getProgressCancel() function, as well as progressUpdate(), displays a confirmation dialog if the use hits the cancel button and returns the cancel status from that confirmation. Unlike progressUpdate(), this function returns true if the user has made a confirmed cancel request and false otherwise.

setProgressCancel <boolean>

Sets or clears the Cancel flag for the progress bar. By passing a value of true, the Cancel flag is set and will be detected by progressUpdate() and getProgressCancel(). By passing a value of false, the Cancel flag is cleared if set.

The following 3ds max system global variable is associated with the Progress Bar display:

escapeEnable

Lets you get and set a Boolean value defining whether ESC key interrupt detection is on or off. Setting enableEscape to false turns ESC key interrupt detection off, setting it to true turns it on again. This variable is useful when used in conjunction with a Progress Bar. You can set enableEscape to false when you don't want the user to be able to interrupt a script running a long computation and you have set up a progress bar with its own Cancel button.


Status Bar Buttons

The following methods are associated with the buttons in 3ds max's Status Bar:

getCrossing()

Returns whether Crossing Selection (true) or Window Selection (false) is set.

getPluginKeysEnabled()

setPluginKeysEnabled <boolean>

Get and set whether Plug-in Keyboard Shortcuts are enabled (true) or disabled (false).

getSnapState()

Returns the Snap toggle state - on (true) or off (false).

getSnapMode()

Returns the current snap type as a string – "ABSOLUTE" or "RELATIVE".

isSelectionFrozen()

Returns true if the node selection is frozen, false if not frozen

freezeSelection()

Freezes the node selection

thawSelection()

Thaws the node selection.

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 Time Configuration Dialog for methods for setting options in the Time Configuration dialog.


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


Accessing Active Viewport Info, Type, and Transforms

The following 3ds max system global variables are associated with the viewports:

viewport.activeViewport

Lets you get and set the index of the active viewport. If you change the currently active viewport to a 2D view, this variable will contain the value 0.

viewport.numViews

Contains the number of 3D viewports in the current viewport layout. This variable is read-only. This variable does not reflect any 2D (Track View, Schematic View, Listener, and so on) views in the viewport layout. So, for example, if viewport.getLayout() returns #layout_4 and this variable contains the value 2, you know that two of the viewports contain 2D views. MAXScript currently does not allow you to access 2D view viewports.

The following methods are used to access active viewport information and transforms:

viewport.getLayout()

viewport.setLayout <view_layout_name>

Gets or sets the viewport layout, where <view_layout_name> specifies the viewport layout configuration. When setting the layout, the view shown in each viewport is based on the configuration set in Customize > Viewport Configuration > Layout. The list of valid <view_layout_name> values below uses the following syntax:

# is the total number of viewports.

V = vertical split

H = horizontal split

L/R = left/right placement

T/B = top/bottom placement

The valid <view_layout_name> values are:

#layout_1 -- 1 viewport

#layout_2v -- 2 viewports, vertical split, both same size

#layout_2h -- 2 viewports, horizontal split, both same size

#layout_2ht –- 2 viewports, horizontal split, top smaller

#layout_2hb -- 2 viewports, horizontal split, top larger

#layout_3vl –- 3 viewports, 2 on left, 1 on right

#layout_3vr -- 3 viewports, 1 on left, 2 on right

#layout_3ht -- 3 viewports, 2 on top, 1 on bottom

#layout_3hb -- 3 viewports, 1 on top, 2 on bottom

#layout_4 -- 4 viewports, all same size

#layout_4vl -- 4 viewports, 3 on left, 1 on right

#layout_4vr -- 4 viewports, 1 on left, 3 on right

#layout_4ht -- 4 viewports, 3 on top, 1 on bottom

#layout_4hb -- 4 viewports, 1 on top, 3 on bottom

viewport.getType()

viewport.setType <name>

Get and set the view type for the current viewport. Valid <name> values are:

#view_top -- Top

#view_bottom -- Bottom

#view_right -- Right

#view_left -- Left

#view_front -- Front

#view_back -- Back

#view_persp_user -- Perspective

#view_iso_user -- User

#view_camera -- Camera

#view_spot -- Light

#view_shape -- Shape

#view_track -- Track View

#view_grid -- Grid

Notes: If the current viewport is an extended viewport (that is, a Track View, Asset Manager, or MAXScript Listener viewport), getType() will return undefined. If a Camera or Light viewport is specified with setType(), and there is not exactly one camera or light selected, a dialog will be displayed for the user to select the camera or light to use.

viewport.setType returns a boolean - true if successful, false if not. Can also get a return value of #view_none. If none of the viewports have focus, a value of false is returned from viewport.getType.

Example:

viewport.setType #view_track -- no viewport is active after this command
viewport.getType() -– will return false

viewport.ResetAllViews()

This function will reset all viewports in Max to the default layout.

getActiveCamera()

viewport.getCamera()

Returns the camera node associated with the active view if any, undefined if none.

viewport.setCamera <camera_node>

Sets the active viewport to a Camera view, using the specified camera.

getViewTM()

viewport.getTM()

viewport.setTM <matrix3>

Get or set the active view screen-to-world transform matrix for non-orthographic (perspective and isometric user views) viewports. This is the affine camera or viewport matrix. setTM only operates on Perspective viewports, and returns a value of true if the view transform matrix was successfully set, false otherwise.

The following function returns as a Ray value the "eye" location and direction for the active viewport. The viewport needs to be a non-orthographic viewport.

Example:

fn getViewDirectionRay =

(

-- The affine TM transforms from world coords to view coords

-- so we need the inverse of this matrix

local coordSysTM = Inverse(getViewTM())

-- The Z axis of this matrix is the view direction.

local viewDir = -coordSysTM.row3

-- get the view position from this matrix

local viewPt = coordSysTM.row4

return ray viewPt viewDir

)

getViewFOV()

Returns the Field of View for the active viewport. If the viewport is an orthographic viewport, a value of 57.2958 degrees (1 radian) is returned.

getViewSize()

Returns the active view size as point2 in pixels.

getScreenScaleFactor <point3>

Returns the active view scale factor, giving the width in world-space units at the point's distance from the view space origin.

mapScreenToWorldRay <pixel_coord_point2>

Returns a Ray value in world space through the given viewport pixel coordinates in the current active view, and perpendicular to the viewport plane.

mapScreenToView <pixel_coord_point2> <depth_float> \

[ <viewport_size_point2> ]

Returns a 3D point in the view coordinate space. Given a point in the active viewport screen (in viewport pixel coordinates), and a depth in view coordinates, this method maps the point into view coordinates. If <viewport_size_point2> is supplied, the specified viewport size is used instead of the actual viewport size.

mapScreenToCP <pixel_coord_point2> [ <viewport_size_point2> ]

Maps viewport pixel coordinates in the current active view to the construction plane in world coordinates. If <viewport_size_point2> is supplied, the specified viewport size is used instead of the actual viewport size.

getCPTM()

Construction-plane-to-world transform matrix.

gw.nonScalingObjectSize()

The value returned from this method may be used as a scale factor that will counteract the viewport zoom. For example, lights, cameras, and tape helper objects use this factor so the size of the node in the scene remains constant when the viewport is zoomed in and out.

This value is affected by the 'Non-Scaling Object Size' spinner in the Viewport Preferences dialog, so the user has some control over this as well.

gw.getPointOnCP <pixel_coord_point2>

Returns a point in world space on the current construction plane based on the specified screen coordinate.

gw.getCPDisp <base_point3> <dir_point3> \

<start_pixel_coord_point2> <end_pixel_coord_point2>

This method returns a length in world space given a start screen point (<start_pixel_coord_point2>), an end screen point (<end_pixel_coord_point2>), a base point (<base_point3>) and a direction vector (<dir_point3>). For example, when creating a cylinder, the user clicks the mouse down to define the center point of the cylinder (base), then drags out a radius. They then drag out a height for the cylinder. This method is used to return intermediate and final heights for the cylinder based on the initial base point, the direction vector (the Z axis), the start mouse point, and the current point the user is interactively adjusting.

gw.getVPWorldWidth <point3>

Returns the viewport screen width factor in world space at a point in world space.

gw.mapCPToWorld <point3>

Returns the corresponding world space point given a point on the construction plane. For example, if you use gw.getPointOnCP() to convert a screen coordinate to a point on the construction plane, you could then call this method to convert that point on the construction plane to a world space point.

gw.IsPerspView()

Returns true if the active viewport is a perspective view; otherwise returns false.

gw.getFocalDist()

Returns the focal distance of an active perspective view.

gw.snapPoint <pixel_coord_point2> [ snapType:<snapType_name> ]

Given a 2D screen coordinate, this method returns a 3D point on the current construction plane based on the current snap settings and the optional snapType parameter. The valid <snapType_name> values are:

#in3d

Snap to all points.

#inPlane

Snap only to points on the construction plane.

#unSelObjs

Ignore selected nodes when considering snap points.

#selObjs

Ignore unselected nodes when considering snap points.

#unSelSubobj

Ignore selected sub-object geometry when considering snap points.

#selSubobj

Ignore unselected sub-object geometry when considering snap points.

#force3d

Override user settings to force snap in 3D.

gw.snapLength <length_float>

This method snaps the length to the nearest snap increment and returns the snapped distance.

units.formatValue <float>

Returns a <string> value representing the <float> in the current unit scale. This method can cause a string overflow, especially when the units are set to miles or kilometers. If an overflow occurs a run-time error is thrown.

units.decodeValue <string>

Parses <string> using the current unit settings and returns a <float>. A run-time error is thrown if an error occurs in the parsing of the string.


Refreshing the Viewports

The following methods force the viewports to redraw, or control when the viewports are redrawn.

redrawViews()

Causes the 3ds max viewports to be immediately redrawn in an optimal way, such that only those parts of the view that have changed are redrawn. This is different from forcing a redraw with the max view redraw command or one of the following methods which redraw the entire scene in all views.

completeRedraw()

forceCompleteRedraw [ doDisabled:<boolean> ]

Calling this method will cause all the viewports to be completely redrawn. This method literally forces everything (every object, every screen rectangle, every view) to be marked invalid and then the whole scene is regenerated. The individual object pipeline caches are not flushed, however. This routine is guaranteed to be slow. If the optional doDisabled: boolean argument for ForceCompleteRedraw is true, disabled viewports will also be redrawn.

disableSceneRedraw()

Turns viewport scene redraw off (disables it). All calls to DisableSceneRedraw()/EnableSceneRedraw() must be in pairs, since an internal counter is used in 3ds max to actually do the redraw enable/disable action.

enableSceneRedraw()

Turns viewport scene redraw on (enables it). All calls to DisableSceneRedraw()/EnableSceneRedraw() must be in pairs, since an internal counter is used in 3ds max to actually do the redraw enable/disable action.

isSceneRedrawDisabled()

Returns true if scene redraw is disabled, false if it is enabled.

nodeInvalRect <node>

Invalidates the rectangle in the viewports that the node is occupying. Rectangles flagged as invalid will be updated on the next screen redraw.


Viewport Background Images

The following methods provide access to the values in the Viewport Background dialog.

getBkgFrameNum <time>

Returns the viewport background image frame displayed at the specified time. Returns a value of –1 if no frame is to be used for specified time.

getBkgImageAnimate()

setBkgImageAnimate <boolean>

Get and set whether Animate Background is on (true), or off (false).

getBkgImageAspect()

setBkgImageAspect <name>

Get and set the background image Aspect Ratio option. Valid <name> values are:

#view -- Match Viewport

#bitmap -- Match Bitmap

#output -- Match Rendering Output

getBkgORType <start_end_integer>

setBkgORType <start_end_integer> <name>

Get and set the background image Start Processing and End Procession options.

<start_end_integer> = 0 – Start Processing; 1 – End Processing

Valid <name> values are:

#blank -- Blank Before Start/After End

#hold -- Hold Before Start/After End

#loop -- Loop After End

getBkgRangeVal()

Get the background image Use Frame range as a Point2 value. The first component of the Point2 value is the Start Frame, the second component is the End Frame.

setBkgFrameRange <point3>

Set the background image Use Frame range and step value. First component of <point3> is Start Frame, second component is End Frame, and third component is Step Frame.

getBkgStartTime()

setBkgStartTime <time>

Get and set the background image Start At frame.

getBkgSyncFrame()

setBkgSyncFrame <integer>

Get and set the background image Synch Start To Frame frame.

The following 3ds max system global variable is associated with the Viewport Background dialog:

backgroundImageFileName

Lets you get and set a String value that defines the viewport background image bitmap file name. It contains the corresponding bitmap file name set in the Viewport Background dialog.


Viewport Grids

The following methods control the display and spacing of grid lines in the viewports.

getGridSpacing()

Returns the spacing between grid lines in units.

getGridMajorLines()

Returns the number of grid lines between major grid lines.

The following 3ds max system global variable is associated with the Viewport grids:

activeGrid

Contains the currently active grid. If the home grid is active, returns the value undefined. You can assign a grid node object to this variable to make it the currently active grid.

You can also return to the home grid by setting activegrid = undefined.


Mouse Cursors

The following methods control the mouse cursor.

setWaitCursor()

setArrowCursor()

These functions can be used to display the system wait cursor during some prolonged computation and then replace it with the normal cursor. You might want to do this instead of putting up a 3ds max progress bar, which may be too heavy-weight in some situations. Note that in some cases, 3ds max may itself restore the arrow cursor underneath this one (for example, with loadMAXFile()), and you may need to redisplay it after such calls.

setSysCur <name>

Sets the current system cursor to one of the standard 3ds max cursors. Valid <name> values are:

#move

#rotate

#uscale

#nuscale

#squash

#select

#arrow

Note: setSysCur #squash shows the non-uniform scale cursor.

The following 3ds max system global variables are associated with the mouse:

mouse.mode

A read only variable to get the mouse mode as an <integer> value. Return values are: 0 - Idle; 1 - Point; 2 - Move

mouse.buttonStates

A read only variable to get the state of the mouse buttons as a 3 element <bitArray>. The order of the bits is: #{Left, Middle, Right}

Note: right mouse button state not always correct. If you right click to bring up a right-click menu and then click in the viewport to dismiss the menu, the right mouse button is still reported as down.

mouse.pos

A read only variable to get the mouse position in the currently active viewport as a <point2> value. The coordinates are in pixel values. If the currently active viewport is a 2D view (Track View, Schematic View, Listener, etc.), the coordinates are in the first non-2D viewport.

mouse.screenpos

A read only variable to get the mouse position on the screen as a <point2> value. The coordinates are in pixel values relative to the top-left corner of the screen.


Picking Points in the Viewports

pickPoint [ prompt:<string> ] [ snap:#2D|#3D ] \

[ rubberBand:<start_point3> ] \

[ mouseMoveCallback:fn | #(fn,arg) ] \

[ terminators:#(<string>,<string>,...) ]

The pickPoint() function lets the user pick a 3D point in a 3ds max viewport or type in a 3D point in the Listener. When called, the function puts 3ds max into a special point-picking command mode and the cursor changes to a cross-hair. The user can either click in one of 3ds max's viewports or type a 3D point into the Listener and the function returns that point as a MAXScript Point3 value in world-space coordinates.

The function takes an optional prompt: string argument which it prints in the Listener as a prompt message. There is also an optional snap: keyword argument that controls viewport point picking if Snap is turned on in the 3ds max interface. If #3D is specified, the cursor snaps to points anywhere in 3D space, if #2D is specified (the default), the cursor only snaps on the current active grid construction plane. If Snap is off in the 3ds max interface, the clicked point is always taken to be on the current active grid construction plane.

The user can either press the ESC key or click the right mouse button at any time to abort the point picking and the function immediately returns the special MAXScript value #escape if the escape key is pressed or #rightClick if the right mouse button is clicked.

You can get the pickPoint() function to display a rubberbanding dashed line during point input by supplying the optional keyword argument rubberBand:<start_point3>. If you include this on a call to pickPoint(), it rubberbands a dashed line from the specified start point to follow the mouse. You would use it in a chain of point picks by specifying the last picked point as the rubberBand: start point for each successive pick. The start point given to rubberBand: should be in world coordinates.

You can also set up a mouse move callback function for tracking free mouse moves during point input. The optional keyword argument for this is mouseMoveCallback: and it has two forms:

mouseMoveCallback:fn

mouseMoveCallback:#(fn, arg)

The second form allows you to supply an argument value that is sent to the callback function each time it is called.

The fn you supply should take one argument in the first form above and two in the second. When the callback function is called, the first argument it gets is always the current world coordinates of the mouse and the second if given is the arg you supplied. You can use a callback function to implement a more sophisticated form of rubberbanding, for example by adjusting a spline's vertex or a box's height to follow the mouse. If you do this, make sure you call any needed update() mesh or spline functions.

The pickPoint() function allows coordinates to be entered either by clicking in a 3ds max viewport or by typing numbers into the MAXScript Listener window. The user can enter coordinates in one of several forms (based on the command line input syntax for AutoCAD), as follows:

x, y, z

explicit point in current construction plane coordinates

x, y

point on the construction plane (cp)

d

point d units away in mouse direction from last point

@ x, y, z

relative, offset to last input point

@ x, y

on cp, relative to last point's projection on cp

d < a

polar on cp, distance from cp origin at a angle from x-axis

@ d < a

relative polar on cp, centered on last point

d < a1 < a2

spherical on cp, d from cp origin at a1 from x and a2 angle from xy-plane

@ d < a1 < a2

relative spherical

There can be zero or more white space characters before and between numbers and metacharacters.

Note that these typed-coordinates are always interpreted as relative to the current active grid construction plane and that coordinates returned by pickPoint() are always in world-space.

Keyboard input by the user that is not in one of the expected coordinate input forms is returned as a String value so the author can handle the error gracefully or permit other kinds of input to be parsed by the script.

You can test for these return conditions using the classOf() function, for example:

p = pickPoint()

case of

(

(p == undefined): ... -- user pressed escape

(p == #rightClick): ... -- user clicked RMB

(classOf p == Point3): ... -- user entered a point

(classOf p == String): ... -- user keyed a non-point

)

The terminators: keyword argument expects an array of 1 or more strings each of 1 or more characters. When supplied, this list of strings specifies a set of keyboard input terminating character sequences. If any one of them is typed at the end of some input, the 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.


Viewport Drawing Methods

The methods documented in this topic provide low-level access to 3ds max's graphics system. These methods are available for scripts to do any graphics work not possible using the standard high-level graphics methods.

These methods are for use in the existing 3ds max viewports, and only work on the active viewport. Note that these methods typically are not for casual use, as they are not intended to be a high level graphics library. For example, many steps are required to display a single lit polygon. These methods are optimized for speed, and not at all for script programmer ease of use.

The methods described in this topic actually operate on graphic windows. While graphic windows are not the same as viewports, they are related to one another. Each viewport has its own graphics window, and the contents of the viewport display can be thought of as a snapshot of the graphics window contents. Since writing to display memory a relatively slow operation, 3ds max writes instead to the graphics window, and then when all the writes have been finished, it redraws the viewports with the graphics window contents.

Graphics Driver Configuration and Support Methods

gw.getDriverString()

This method returns a string identifying the graphics driver (and includes manufacturer info if available)

gw.querySupport <feature_name>

Determines if the driver supports the specified feature. The valid <feature_name> values are:

#txtCorrect

This is used to enable or gray-out the perspective correction right-click viewport menu option.

#geomAccel

This is used to indicate to 3ds max (and the mesh class in particular) that the driver wants to handle all of the 3D data natively. In this case, meshes are rendered by passing 3D world space data and letting the driver transform, clip, and light the vertices. If this returns false, then the mesh class handles all transforms, clipping and lighting calculations and then calls the hPolygon or hPolyline 2 1/2D calls for the driver to rasterize. (Primitives that are actually clipped are still sent to the polygon/polyline methods.)

Currently, only the OpenGL driver returns true to this query, but other drivers have been developed that return true, and the HEIDI and D3D drivers may change in the future.

#triStrips

If this returns true, then 3ds max will try to stripify meshes before calling the rendering methods. Currently, the drivers just return the user preference that is set in the driver configuration dialog. This preference defaults to true.

#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).

Window and Viewport Transformation Methods

gw.isPerspectiveView()

Returns true if the view is in perspective projection; otherwise false (orthographic projection).

gw.setTransform <matrix3>

Sets the active viewport's graphics window transformation matrix to the specified matrix3 value, and updates the modeling coordinates to normalized projection coordinates matrix. This routine also back-transforms each light and the eye point so that lighting can be done in modeling coordinates.

This method may be used to set a matrix that transforms the point passed to the drawing methods (like gw.text(), gw.marker(), gw.polyline() or gw.polygon()). Normally these methods expect world coordinates. However if this matrix is set to an object's transformation matrix you can pass coordinates in the object's space coordinates and they will be transformed into world space (and then put into screen space when they are drawn). If however this is set to the identity matrix, you would pass world space coordinates. You can set this matrix to the object's transform matrix using the following code:

gw.setTransform node.transform

For world-to-screen space conversions by the methods gw.text(), gw.marker(), gw.polyline() or gw.polygon(), etc, a developer must explicitly set this matrix to the identity matrix. This is because the graphics window may have a non-identity transform matrix already in place from a previous operation.

gw.getFlipped()

Returns true if the determinant of the current transform is positive, false if negative.

Position, Size, and Depth Clipping Methods

gw.setPos <x_integer> <y_integer> <w_integer> <h_integer>

Sets the size and position of the graphics window. The coordinates are all Windows coordinates in the space of the graphics windows' parent window. All coordinates are in Windows format, with the origin in the upper left.

x - Specifies the left graphics window origin; y - Specifies the top graphics window origin; w - Specifies the graphics window width; h - Specifies the graphics window height.

gw.getWinSizeX()

This method gets the current window size in X.

gw.getWinSizeY()

This method gets the current window size in Y.

gw.getWinDepth()

This method returns the z-buffer depth (in bits). Note: this method does not return the proper Z depth value in 3ds max and VIZ R3.

gw.getHitherCoord()

This method returns the largest device Z value.

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.

Example:

MacroScript GrabViewport category:"Tools" tooltip:"Grab Viewport"

(

---------------------------------------------------------------------

--GRABVIEWPORT MACROSCRIPT

--Created:3/23/99

--Edited:4/28/99

--by Borislav Petrov

--bobo@email.archlab.tuwien.ac.at

---------------------------------------------------------------------

--Snapshot Active Viewport to Bitmap

--Filename in format:

--VPGRAB_MaxFileName_ViewportName_CurentFrame.ImageFormatExtension

---------------------------------------------------------------------

--

--Init Variables

local grab_bmp --bitmap to put the snapshot into

local bmp_name --name of the bitmap to save

local get_viewport_name --viewport name

local gac,gct,mfn --variables to hold ActiveCamera, CurrentTime, MaxFileName

--

--Start Macro

grab_bmp = gw.getViewportDib() --get the viewport bitmap into variable

get_viewport_name = viewport.GetType() --get viewport name

gvn = get_viewport_name as string --convert viewport name to string

gvn = substring gvn 6 (gvn.count-5) --cut the string

if gvn == "camera" then --if the remaining string is "camera"

(

gac = getActiveCamera() --get the camera

gvn = gac.name --get the name of the camera

)

mfn = MaxFileName --get max file name

if mfn == "" then --if there is no name

mfn = "Untitled" --use "Untitled"

else

mfn = getFileNameFile mfn --use the file name without .MAX extension

gct = SliderTime as string --get current frame time

--

bmp_name = "VPGRAB_"+ mfn +"_" +gvn + "_" + gct --build the output file name

--

--Display file save dialog

bmp_name = getSaveFileName caption:"Save Viewport to:" filename:bmp_name \

types:"BMP(*.bmp)|*.bmp|TIFF(*.tif)|*.tif|JPG(*.jpg)|*.jpg|TGA(*.tga)|*.tga|"

--

if bmp_name != undefined then --if user has confirmed / entered a valid name

(

grab_bmp.filename = bmp_name --set output name to the one entered in the save file dialog

save grab_bmp --save the bitmap

display grab_bmp --display the bitmap in a VFB

)

--

)--end of script

Drawing Setup

gw.resetUpdateRect()

This method resets the update rectangle. The update rectangle is the region of the screen that needs to be updated to reflect items that have changed. When the system is done rendering items, the goal is to only update the region of the viewport that has actually been altered. This method sets the update rectangle (the region that will be blitted to the display) to a special "empty" value. This way when gw.enlargeUpdateRect() is later called, the Box2 region passed will be used as the region.

gw.enlargeUpdateRect ( <Box2> | #whole )

This method enlarges the update rectangle to include the Box2 value passed. If #whole is specified, the whole viewport will later be updated

gw.getUpdateRect()

This method retrieves the current update rectangle as a Box2 value. Returns a special an Box2 "empty" value if no region of the viewport needs to be updated.

gw.setRndLimits <render_limits_name_array>

Sets the rendering limits used by primitive calls. Setting the rendering limits is used in communication between the various parts of 3ds max that handle the display of objects. For example, setting this limit to #polyEdges and then drawing a polygon won't result in a polygon drawn with edges. It only sets a flag that indicates the edge should be drawn.

What happens is as follows. Inside the upper level 3ds max, part of the code knows that polygon edges have been turned on. However this is not related through the object oriented architecture to the part of 3ds max that does the actual drawing. When 3ds max goes to draw objects it will see that the polygon edge flag is on. This tells it to do two drawing passes -- one to draw the polygon, then it calls outlinePass() call with true, draws a bunch of edges, then calls outlinePass() with false. Thus, the drawing routine is responsible for looking at the flags and drawing appropriately. This method is only responsible setting the limit which can later be checked.

<render_limits_name_array> specifies the rendering limits used by the viewport as an array of <render_limits_name> values. The valid <render_limits_name> values are:

#allEdges

All edges of the item are shown (including hidden ones).

#boxMode

Objects are shown using their bounding box.

#backcull

Backface culling is used. Entities whose surface normal face away from the view direction are not drawn.

#colorVerts

This turns on color-per-vertex display.

#flat

Flat (facet) shading mode.

#illum

This indicates that you have colors per vertex in your polygons and that they should be used. If you had colors per vertex but this flag was not set, the colors would be ignored.

#lighting

This is the same as setting #illum and #specular.

#noAtts

No attributes are specified.

#perspCorrect

In this mode textures are corrected for perspective display.

#pick

This indicates hit testing will be performed (not rendering).

#polyEdges

This mode causes polygon edges (Edged Faces) to be on.

#shadeCverts

This modifies #colorVerts. If set, lighting is enabled and the vertex colors are used to modulate the colors that result from lighting. If off, the colors on each vertex are used directly to shade the triangle. When 3ds max uses #shadeCverts mode, it puts a white diffuse-only material on the object so that it appears that the colors are shaded without distortion.

Described further, when #shadeCverts is OFF, then the vertex colors are used directly. This is equivalent to saying that they are modulated by a pure white self-illuminated material.

When #shadeCverts is ON, the diffuse white material is illuminated by the scene lighting, resulting in shades ranging from black to white, with most vertices being some shade of pure gray. When the vertex colors are modulated by the material color, they get multiplied (in general) by a number less than 1, which makes them appear darker.

The RGB components of the colors are modulated uniformly, so that there is no shift from, say, red to green. That would happen if the underlying material was not evenly weighted (that is, a pure gray lying between black and white). Said another way, only the intensity of the vertex colors is changed when shading is on, not luminance, chrominance, etc.

#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.

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.

Drawing Methods

Methods that start with "h" take integer device coordinates with the origin at the lower-left. Methods that start with "w" in front take Windows device coordinates with the origin at the upper left. These "h" and "w" routines perform NO clipping unless otherwise noted. Drawing outside the allowable region is likely to cause 3ds max to crash. These coordinate systems are left-handed.

Methods that don't start with "h" or "w" map points from the graphic window's current transform to device space. This coordinate system is right-handed. If the graphic window's transform is set to the identity matrix then the mapping is done from points specified in world space. Otherwise the points given are transformed by the graphic window's transform, and are then considered to be in world space. Thus, to get a world-space to screen-space conversion, you need to set the graphic window's transform to the identity with:

gw.setTransform(Matrix3 1)

After completing any drawing to the graphics window with the methods described in this section, you need to call gw.updateScreen() to update the viewport display.

gw.updateScreen()

Updates the viewport display to display any text, markers, polylines, polygons, or tristrips written to the graphics window via the methods described below.

gw.text <point3> <string> [ color:<color> ]

gw.hText <point3> <string> [ color:<color> ]

gw.wText <point3> <string> [ color:<color> ]

Draws 2D fixed font annotation string text to the specified location using the specified (optional) color. If the color is not specified, a default color of red is used.

Note: This routine DOES perform clipping of the text if it is off the screen.

gw.Marker <point3> <marker_name> [ color:<color> ]

gw.hMarker <point3> <marker_name> [ color:<color> ]

gw.wMarker <point3> <marker_name> [ color:<color> ]

Draws a marker at the specified location. This is can be paired with pickpoint() to quickly show where the user has clicked. These markers are temporary and will be erased whenever the viewports are updated. If the color is not specified, a default color of red is used. The valid <marker_name> types are:

#point

#hollowBox

#plusSign

#asterisk

#xMarker

#bigBox

#circle

#triangle

#diamond

#smallHollowBox

#smallCircle

#smallTriangle

#smallDiamond

The following is an example that creates an instance of all types of markers, spaced equally:

arr = #("point","hollowBox","plusSign","asterisk","xMarker",

"bigBox","circle","triangle","diamond","smallHollowBox",

"smallCircle","smallTriangle","smallDiamond" )

for i=1 to arr.count do

gw.hMarker [100, (50 + i*10), 50](arr[i] as name)

gw.enlargeUpdateRect #whole

gw.updateScreen()

gw.Polyline <vertex_point3_array> <isClosed_boolean> \

[ rgb:<color_array> ]

gw.hPolyline <vertex_point3_array> <isClosed_boolean> \

[ rgb:<color_array> ]

gw.wPolyline <vertex_point3_array> <isClosed_boolean> \

[ rgb:<color_array> ]

This method draws a multi-segment polyline. Each value in <vertex_point3_array> is a vertex on the polyline. If <isClosed_boolean> is true, the first point is connected to the last point, that is, the polyline is closed. If false, the polyline is left open. If the optional rgb color array is specified, and shade mode is set to smooth, the polyline will be drawn Gourand shaded. This is how 3ds max draws lit wireframes for instance. If the optional rgb color array is not specified, the line is drawn with the line color specified via gw.setColor(). The number of elements in <color_array> must be the same as in <vertex_point3_array>.

gw.Polygon <vertex_point3_array> <color_array> \

<uvw_point3_array>

gw.hPolygon <vertex_point3_array> <color_array> \

<uvw_point3_array>

gw.wPolygon <vertex_point3_array> <color_array> \

<uvw_point3_array>

This method draws a multi-point polygon. Each value in <vertex_point3_array> is a vertex on the polygon. <color_array> specifies the color at each vertex. The rendering mode (set via gw.setRndLimits()) must include #illum for the color values to be used. <uvw_point3_array> specifies the UVW coordinates at each. The rendering mode must include #texture for the UVW coordinates to be used. The number of elements in each array must be identical.

gw.hTriStrip <vertex_point3_array> <color_array> \

<uvw_point3_array>

gw.wTriStrip <vertex_point3_array> <color_array> \

<uvw_point3_array>

This method is used for drawing a series of triangles specified as 'strips'. It takes a count of 3 or more, and builds triangles in a strip. This sends a lot less data and the underlying graphics library has to set up a lot less data since it can use the previous information to start the rasterization. This results in a significant speed increase. This routine does no clipping so all the vertices passed must be within view. The parameters are the same as for the gw.Polygon(). However, how the <vertex_point3_array> is handled is different. After the first two vertices, each new vertex is used to create a new triangle. For instance, to draw a quad, the first three vertices specify the first triangle and the next one is combined with the previous two to complete the square

The following is an example of using the above functions:

Example:

-- Draw some primitives

gw.hPolyline #([300,50,16], [300,200,8], [450,250,4]) true

--

gw.hPolygon #([200,100,16], [280,100,8], [250,200,4]) \

#(red, blue, green) \

#([1.0,.5,0], [0.5,0.5,0], [0,0,0.5])

--

gw.hTriStrip #([50,50,0], [175,100,0], [25,100,0], [150,250,0]) \

#(red, blue, green, white) \

#([1.0,.5,0], [0.5,0.5,0], [0,0,0.5], [0.5,1,0])

--

-- Update the viewports

gw.enlargeUpdateRect #whole

gw.updateScreen()

gw.setColor <type_name> <color_value>

Sets the RGB color used for the specified drawing type. The valid <type_name> values are:

#line -- line drawing color

#fill -- polygon fill color

#text -- text drawing color

#clear -- The color that the viewport is cleared to

when you call gw.clearScreen()

gw.clearScreen <Box2> [ useBkg:<boolean> ]

Clears the specified rectangular region of the screen. If the optional useBkg parameter is set to false, the region is set to the "clear" color (see gw.setColor() above). If true, the background should be used to fill the cleared area. The default useBkg value is false.


Miscellaneous Viewport Methods and System Globals

createPreview()

Creates a viewport preview using the current values in the Make Preview dialog.

getVPortBGColor()

setVPortBGColor()

Get and set the viewport background color as a Color value.

isCPEdgeOnInView()

This method returns true if the construction plane is 'head on' in the current viewport. For example if the construction plane was XY and you were looking from the Front view, this method would return true. This is used for example during object creation because this process doesn't work very well when the view is 'head on'.

axisTripodLocked()

This method returns true if the axis tripods are locked, that is, they won't move when you move an object or sub-object, false otherwise.

lockAxisTripods <boolean>

If <boolean> is true, this method locks the axis tripods so that they will not be updated. If false, the axis tripods will be updated.

Note: In certain cases, the lockAxisTripods() method can cause multiple Assertion Failures. This occurs when one or more objects are selected, lockAxisTripods true is executed, and then the objects are deselected.

flashNodes <node_array>

This method is used to 'flash' a group of nodes. This is usually used as a confirmation of some operation (for example as an indication of the completion of a pick node operation.) The nodes are briefly erased and then redrawn in the viewport to flash them.

Note: The flashNodes() method does not redraw the viewports after displaying the specified nodes as white wireframes. To properly redraw the viewports, call the forceCompleteredraw() method immediately after calling flashNodes().

The following 3ds max system global variables are applicable to the viewports:

displaySafeFrames

Lets you get and set whether Show Safe Frames is on for the active viewport. A Boolean value - true if Show Safe Frames is on, false if off.

preferences.useLargeVertexDots

Lets you get and set whether to use small or large dots when representing vertices as dots. A Boolean value set to true if you when using dots to represent vertices and a large size is desired. The value of this variable only has effect when UseVertexDots is set to true. This variable contains the corresponding value set in the Viewports page of Customize > Preferences.

preferences.useTransformGizmos

Lets you get and set whether to use the Transform Gizmos. A Boolean value - true if on, false if off. This variable contains the corresponding value set in the Viewports page of Customize > Preferences.

preferences.useVertexDots

Lets you get and set whether to represent vertices as dots. A Boolean value set to true when you want to use dots as the representation of the vertices in a mesh. If set to false, ticks will be used. This variable contains the corresponding value set in the Viewports page of Customize > Preferences.


3ds max User Interface Colors

The following methods are used to get and set the 3ds max user interface colors.

GetUIColor <index_integer>

Returns a Point3 value corresponding to the color value used for drawing the specified item type in the 3ds max viewports. Each component of the Point3 value is in a range of 0 to 1, corresponding to a color component value of 0 to 255. See the list of <index_integer> values below.

GetDefaultUIColor <index_integer>

Returns a Point3 value corresponding to the default color used for drawing the specified item type in the 3ds max user interface. Each component of the Point3 value is in a range of 0 to 1, corresponding to a color component value of 0 to 255. The values returned are not affected by the user's color selections or those set by SetUIColor(). See the list of <index_integer> values below.

SetUIColor <index_integer> <point3>

Sets the color value used for drawing the specified item type in the 3ds max viewports. Each component of the Point3 value is in a range of 0 to 1, corresponding to a color component value of 0 to 255. See the list of <index_integer> values below.

The valid <index_integer> values and the corresponding item type are as follow:

0 COLOR_SELECTION Main UI Selection

1 COLOR_SUBSELECTION Main UI Subselection

2 COLOR_FREEZE Main UI Freeze

3 COLOR_GRID Grids Grid

4 COLOR_GRID_INTENS Grids Grid Intensity

5 COLOR_SF_LIVE Main UI Safe Frame Live

6 COLOR_SF_ACTION Main UI Safe Frame Action

7 COLOR_SF_TITLE Main UI Safe Frame Title

8 COLOR_VP_LABELS Main UI Viewport Label

9 COLOR_VP_INACTIVE Main UI Inactive Viewport Label

10 COLOR_ARCBALL Main UI Arcball

11 COLOR_ARCBALL_HILITE Main UI Arcball Highlight

12 COLOR_ANIM_BUTTON Main UI Animate Button

14 COLOR_LINK_LINES Gizmos & Apparatuses Bones and Link Lines

15 COLOR_TRAJECTORY Gizmos & Apparatuses Trajectory

16 COLOR_ACTIVE_AXIS Gizmos & Apparatuses Active Axis

17 COLOR_INACTIVE_AXIS Gizmos & Apparatuses Inactive Axis

18 COLOR_SPACE_WARPS Objects Space Warp

19 COLOR_DUMMY_OBJ Objects Dummy Object

20 COLOR_POINT_OBJ Objects Point Object

21 COLOR_POINT_AXES Objects Point Axis

22 COLOR_TAPE_OBJ Objects Tape Object

24 COLOR_GIZMOS Gizmos & Apparatuses Gizmos

25 COLOR_SEL_GIZMOS Gizmos & Apparatuses Selected Gizmos

26 COLOR_SPLINE_VECS Main UI Spline Vectors

27 COLOR_SPLINE_HANDLES Main UI Spline Handles

29 COLOR_PARTICLE_EM Gizmos & Apparatuses Particle Emitter

30 COLOR_CAMERA_OBJ Objects Camera Object

31 COLOR_CAMERA_CONE Gizmos & Apparatuses Camera Cone

32 COLOR_CAMERA_HORIZ Gizmos & Apparatuses Camera Horizon

33 COLOR_NEAR_RANGE Gizmos & Apparatuses Camera Near Range

34 COLOR_FAR_RANGE Gizmos & Apparatuses Camera Far Range

35 COLOR_LIGHT_OBJ Objects Light Object

36 COLOR_TARGET_LINE Gizmos & Apparatuses Target Line

37 COLOR_HOTSPOT Gizmos & Apparatuses Light Hotspot

38 COLOR_FALLOFF Gizmos & Apparatuses Light Falloff

39 COLOR_START_RANGE Gizmos & Apparatuses Light Far Start

40 COLOR_END_RANGE Gizmos & Apparatuses Light Far End

41 COLOR_VIEWPORT_BKG Main UI Viewport Background

42 COLOR_TRAJ_TICS_1 Gizmos & Apparatuses Trajectory Frames 1

43 COLOR_TRAJ_TICS_2 Gizmos & Apparatuses Trajectory Frames 2

44 COLOR_TRAJ_TICS_3 Gizmos & Apparatuses Trajectory Frames 3

45 COLOR_GHOST_BEFORE Main UI Ghost (Before)

46 COLOR_GHOST_AFTER Main UI Ghost (After)

47 COLOR_12FIELD_GRID Main UI 12-Field Grid

48 COLOR_START_RANGE1 Gizmos & Apparatuses Light Near Start

49 COLOR_END_RANGE1 Gizmos & Apparatuses Light Near End

50 COLOR_CAMERA_CLIP Gizmos & Apparatuses Camera Clip

51 COLOR_NURBS_CV Main UI NURBS Control Vertex

52 COLOR_NURBS_LATTICE Main UI NURBS Lattice

53 COLOR_NURBS_CP Main UI NURBS Con Point

54 COLOR_NURBS_FP Main UI NURBS Fit Point

55 COLOR_NURBS_DEP Main UI NURBS Dep Object

56 COLOR_NURBS_ERROR Main UI NURBS Error Object

57 COLOR_NURBS_HILITE Main UI NURBS Hilite

58 COLOR_NURBS_FUSE Main UI NURBS Fuse

59 COLOR_END_EFFECTOR Gizmos & Apparatuses End Effector

60 COLOR_END_EFFECTOR_STRING Gizmos & Apparatuses End Effector String

61 COLOR_JOINT_LIMIT_SEL Gizmos & Apparatuses Selected Joint Limits

62 COLOR_JOINT_LIMIT_UNSEL Gizmos & Apparatuses Joint Limits

63 COLOR_IK_TERMINATOR Gizmos & Apparatuses IK Terminator

64 COLOR_SF_USER Main UI Safe Frame User

65 COLOR_VERT_TICKS Main UI Vertex Ticks

66 COLOR_XRAY Main UI See Through

67 COLOR_GROUP_OBJ Objects Group Object

68 COLOR_MANIPULATOR_X Gizmos & Apparatuses Transform Gizmo X

69 COLOR_MANIPULATOR_Y Gizmos & Apparatuses Transform Gizmo Y

70 COLOR_MANIPULATOR_Z Gizmos & Apparatuses Transform Gizmo Z

71 COLOR_MANIPULATOR_ACTIVE Gizmos & Apparatuses Active Transform Gizmo

72 COLOR_VPT_CLIPPING Main UI Viewport Clipping

73 COLOR_DECAY_RADIUS Gizmos & Apparatuses Light Decay Start

74 COLOR_VERT_NUMBERS Main UI Vertex Numbers

75 COLOR_CROSSHAIR_CURSOR Main UI Cross Hair Cursor

76 COLOR_SV_WINBK Other Views SV Window Bkg

77 COLOR_SV_NODEBK Other Views SV Node Bkg

78 COLOR_SV_SELNODEBK Other Views SV Selected Node Bkg

79 COLOR_SV_NODE_HIGHLIGHT Other Views SV Node Highlight

80 COLOR_SV_MATERIAL_HIGHLIGHT Other Views SV Material Highlight

81 COLOR_SV_MODIFIER_HIGHLIGHT Other Views SV Modifier Highlight

82 COLOR_SV_PLUGIN_HIGHLIGHT Other Views SV Plugin Highlight

83 COLOR_SV_SUBANIM_LINE Other Views SV Sub-Anim Line

84 COLOR_SV_CHILD_LINE Other Views SV Child Line

85 COLOR_SV_FRAME Other Views SV Frame

86 COLOR_SV_SELTEXT Other Views SV Selected Label

87 COLOR_SV_TEXT Other Views SV Label

88 COLOR_UNSEL_TAB Main UI Unselected Tabs

89 COLOR_ATMOS_APPARATUS Gizmos & Apparatuses Atmospheric Apparatuses

90 COLOR_SUBSELECTION_HARD Main UI SubSelection Hard

91 COLOR_SUBSELECTION_MEDIUM Main UI SubSelection Medium

92 COLOR_SUBSELECTION_SOFT Main UI SubSelection Soft

93 COLOR_SV_UNFOLD_BUTTON Other Views SV Unfold Children Button

94 COLOR_SV_GEOMOBJECT_BK Other Views SV Geometry Node Bkg

95 COLOR_SV_LIGHT_BK Other Views SV Light Node Bkg

96 COLOR_SV_CAMERA_BK Other Views SV Camera Node Bkg

97 COLOR_SV_SHAPE_BK Other Views SV Shape Node Bkg

98 COLOR_SV_HELPER_BK Other Views SV Helper Node Bkg

99 COLOR_SV_SYSTEM_BK Other Views SV System Node Bkg

100 COLOR_SV_CONTROLLER_BK Other Views SV Controller Node Bkg

101 COLOR_SV_MODIFIER_BK Other Views SV Modifier Node Bkg

102 COLOR_SV_MATERIAL_BK Other Views SV Material Node Bkg

103 COLOR_SV_MAP_BK Other Views SV Map Node Bkg


Material Editor

The following functions are specific to materials and the use of materials with the Material Editor:

getMeditMaterial <slot_index>

you can get the materials in the material editor slots 1 through 24. For example:

foo = getMeditMaterial 3

setMeditMaterial <slot_index> <material>

complements the getMeditMaterial function allowing you to place a material into the numbered material editor slots. Accepts either materials or texture maps as <material>.

loadDefaultMatLib()

Loads the default 3ds max material library file.

loadMaterialLibrary <filename_string>

Loads the named 3ds max material library file, which becomes the current material library. If the file name does not have a fully specified directory path, the function searches through all the currently configured bitmap paths. Returns true if the loads succeeds, false if it fails.

saveMaterialLibrary <filename_string>

Saves the current material library into the named file. Returns true if the save succeeds, false if it fails.

fileOpenMatLib()

This method displays the File Open dialog and allows the user to select a material library to load.

fileSaveAsMatLib()

Displays the standard Save File As dialog to allow the user to save the current material library.

fileSaveMatLib()

If the current material library has been saved previously (has been named) this method saves the material library to the same file. Otherwise it displays the standard Save File As dialog to allow the user to save the current material library.

getMatLibFileName()

Returns the current material library file name as a String value.

renderMap <textureMap> [ into:<bitmap> ] \

[ size:<point2> ] \

[ filename:<string> ] \

[ scale:<float> ] \

[ filter:<boolean> ] \

[ display:<boolean> ]

provides access to the Render Map function available in the Material Editor. The function returns a Bitmap value containing a rendering of the given texture map. If you specify the optional into: argument, the function renders the map into the supplied bitmap, taking size and other attributes from the existing bitmap. If you don't, a new bitmap value is created using the size: and fileName: arguments in its creation. If the into: and size: parameters are not specified, the default size in [200,200].

The scale: argument is a scale factor applied to 3D TextureMaps. This is the scale of the surface in 3d space that is mapped to UV and controls how much of the texture appears in the bitmap representation.

If the filter: argument is true, the bitmap is filtered. It is quite a bit slower to rescale bitmaps with filtering on. Defaults to false.

If the display: argument is true, the resulting bitmap is displayed using the virtual frame buffer; otherwise it is not. Defaults to false.

Example:

rm = renderMap $foo.material.diffuseMap size:[640,480] \

fileName:"foodif.bmp"

save rm

close rm

The above will render a map to a bitmap and save it as a .bmp file.

showTextureMap <material> <texmap> <boolean>

This provides control over the visibility of textures in the shaded viewport. You specify the material containing the texture map, the texture map in that material to be controlled and a boolean to turn the display on or off, for example:

Example:

showTextureMap $foo.material $foo.material.diffuseMap on

tm = checker()

mat = standardMaterial diffuseMap:tm

mm = multimaterial()

mm[1] = mat

$box01.material = mm

showTextureMap mm[1] tm on

Note that for multimaterials, you need to specify the appropriate sub-material (using [] indexing, for example).

The following 3ds max system global variables are applicable to the Material Editor:

currentMaterialLibrary

Contains a virtual array of materials and root level maps corresponding to the currently opened material library. You can get library materials via array indexing and iterate over them in a for loop. The array can be indexed by number, or by name or string to select by material name. This variable is read-only. See MaterialLibrary Values 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 MaterialLibrary Values 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 MaterialLibrary Values for more information.


Track View

The Track View window functions are in a structure package named trackView. These functions operate on named Track Views, and in many cases you identify the Track View window by this name. The Track View functions are:

trackView.open <name_string>

Opens an existing Track View with the specified name, or creates a new Track View with specified name. Returns the value true.

trackView.zoomSelected <name_string>

Zoom the named Track View on the currently selected object. The World track must be expanded for this function to operate. The Object track will automatically be expanded if is closed. The hierarchy display is scrolled such that the selected object's track is placed at the top of the window. If multiple objects are selected, the first object in the hierarchy that is selected will be placed at the top of the window. If there are no selected objects, no operation occurs. This method will return true, except when the named Track View does not exist or is not open, when it returns false.

trackView.close <name_string>

Closes the named Track View. This method will return true, except when the named Track View does not exist or is not open, when it returns false.

trackView.numTrackViews()

Returns the number of named Track Views defined

trackView.getTrackViewName <index_integer>

Returns the name of the indexed Track View as a String. Index values are 1-based.

trackView.setFilter "name_string" {<filter_flag_name>} [#noRedraw]

trackView.clearFilter "name_string" {<filter_flag_name>} [#noRedraw]

These methods allow you to set and clear display filters flags to control what is visible in a named Track View. This method will return true, except when the named Track View does not exist or is not open, when it returns false. You can supply as many filter flags as desired per call. The valid filter flag names are:

#all -- set or clear all flags

#default -- set default view flags

#selectedObjects

#selectedTracks

#animatedTracks

#spacewarpBindings

#modifiedObjects

#transforms

#baseObjects

#positionX

#positionY

#positionZ

#rotationX

#rotationY

#rotationZ

#scaleX

#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. This variable is read-only.

trackViewNodes

Contains a MAXTVNode value that defines top-level World node in Track View. See Track View Nodes. This variable is read-only.

videoPostTracks

Contains a MAXTVNode value that defines the top-level Video Post Track View node. See Track View Nodes. This variable is read-only. This variable contains the value undefined in 3D Studio VIZ.


Render Scene Dialog

Note: Changing the render scene dialog settings via the scripter should be done with the actual render scene dialog in a closed state. Leaving the dialog open will make the attempted scripter modifications non-sticky.

The following methods get and set options in the Render Scene dialog:

getRendApertureWidth()

Get the Aperture Width in millimeters for the current renderer.

getRendImageAspect()

Get the Image Aspect Ratio for the current renderer.

getUseDraftRenderer()

Returns true if the Draft renderer is the default renderer, false if the Production renderer is the default renderer.

SetUseDraftRenderer <boolean>

Specifies which renderer is active -- draft or production. Pass true to use the draft renderer and false to use the production renderer.

The following 3ds max system global variables are applicable to the Render Scene dialog:

renderer

Lets you switch between the draft and production renderers and test which one is active. A Name value that accepts and contains the values #draft or #production, for example:

if renderer == #draft then ...

renderer = #production

render camera:c ...

renderDisplacements

Lets you get and set whether to perform displacement mapping during a render. A Boolean value - true if displacement mapping is to be performed, false if not.

renderEffects

Lets you get and set whether to perform Render Effects after a scene render. A Boolean value - true if Render Effects are to be performed, false if not.

renderHeight

Lets you get and set an Integer value that defines the output size height for the active renderer.

renderPixelAspect

Lets you get and set an Integer value that defines the output pixel aspect for the active renderer.

renderWidth

Lets you get and set an Integer value that defines the output size width for the active renderer.

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

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.

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 3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters.

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

Blendfilter:

Blendfilter ...

<Blendfilter>.Blend Float default: 0.3

Catmull_Rom:

Catmull_Rom()

Cook_Variable:

Cook_Variable()

Cubic:

Cubic()

Mitchell_Netravali:

Mitchell_Netravali ...

<Mitchell_Netravali>.Blur Float default: 0.3333

<Mitchell_Netravali>.Ringing Float default: 0.3333

Plate_Match_MAX_R2: (3ds max only)

Plate_Match_MAX_R2()

Plate_Match_VIZ_R2: (3D Studio VIZ only)

Plate_Match_VIZ_R2()

Quadratic:

Quadratic()

Sharp_Quadratic:

Sharp_Quadratic()

Soften:

Soften()

Video:

Video()


Schematic View

The Schematic View window functions are in a structure package named schematicView. These functions operate on named Schematic Views, and in many cases you identify the Schematic View window by this name. The Schematic View functions are:

schematicView.open <name_string>

Opens an existing Schematic View with the specified name, or creates a new Schematic View with specified name. Returns the value true.

schematicView.zoomSelected <name_string>

Zooms the named Schematic View on the currently selected objects. The display is zoomed such that all of the selected objects are displayed. If there are no selected objects, no operation occurs. This method will return true, except when the named Schematic View does not exist or is not open, when it returns false.

schematicView.close <name_string>

Closes the named Schematic View. This method will return true, except when the named Schematic View does not exist or is not open, when it returns false.

schematicView.numSchematicViews()

Returns the number of named Schematic Views defined

schematicView.getSchematicViewName <index_integer>

Returns the name of the indexed Schematic View as a String. Index values are 1-based.


Time Configuration Dialog

The following methods get and set options in the Time Configuration dialog:

getKeyStepsPos()

setKeyStepsPos <boolean>

Get and set whether to jump to next position key when Key Mode Toggle is on.

getKeyStepsRot()

setKeyStepsRot <boolean>

Get and set whether to jump to next rotation key when Key Mode Toggle is on.

getKeyStepsScale()

setKeyStepsScale <boolean>

Get and set whether to jump to next scale key when Key Mode Toggle is on.

getKeyStepsSelOnly()

setKeyStepsSelOnly <boolean>

Get and set whether to use Selected Objects Only when Key Mode Toggle is on.

getKeyStepsUseTrans()

setKeyStepsUseTrans <boolean>

Get and set whether to Use Current Transform when Key Mode Toggle is on.

The following 3ds max system global variables are applicable to the Time Configuration dialog:

animationRange

Lets you get and set an Interval value that defines the start and end of the current active animation range. It contains the corresponding values set in the Time Configuration dialog.

frameRate

Lets you get and set an Integer value that defines the current scene frame rate in frames-per-second. It contains the corresponding value set in the Time Configuration dialog.

playActiveOnly

Lets you get and set whether to playback the active viewport only. It contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Active Viewport Only is on, false if off.

realTimePlayback

Lets you get and set whether to playback in real time mode. It contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Real Time is on, false if off.

timeConfiguration.playActiveOnly

Lets you get and set whether to playback the active viewport only. It contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Active Viewport Only is on, false if off.

timeConfiguration.playbackSpeed

Get/set viewport playback speed as an indexed <integer>. The valid values for the integer are: 1 - 1/4x, 2 - 1/2x, 3 - 1x, 4 - 2x, 5 - 4x.

timeConfiguration.realTimePlayback

Lets you get and set whether to playback in real time mode. It contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Real Time is on, false if off.

timeConfiguration.useTrackBar

Lets you get and set the state of the Time Configuration dialog 'Key Steps / Use TrackBar' check box. A Boolean Value – true if checked, false if not.


RAMPlayer

The following method is associated with the RAMPlayer:

RAMPlayer <filename1_string> <filename2_string>

Opens RAMPlayer with filename1 as Channel A and filename2 as Channel B. You can pass a null string ("") as a filename string, in which case no file is loaded into that channel.


Track View Pick Dialog

The Track View Pick dialog displays the hierarchy for the 3ds max scene in a manner similar to what is seen in Track View. The user can select one or more items from this dialog. The following method displays the Track View Pick dialog:

trackView.pickTrackDlg [#multiple]

This method brings up the Track View Pick dialog and returns a TrackViewPick value when the user selects a track and clicks "Ok", or undefined if the user clicks "Cancel". If the optional argument #multiple is passed, multiple tracks can be picked in the dialog and an array of TrackViewPick values is returned instead of single value.

TrackViewPick : Value

Instances of the TrackViewPick class store the result of a selection from the Track View Pick dialog. A TrackViewPick value has the following properties:

<trackViewPick>.name : string

The name of the picked item as shown in the Track View Pick dialog.

<trackViewPick>.anim : subAnim

The subAnim for the item the user picked.

<trackViewPick>.client : MAXWrapper

The owner of the subAnim for the item the user picked. If the owner is a subclass of MAXWrapper, the MAXWrapper value for the owner is returned, otherwise a value of undefined is returned.

<trackViewPick>.subNum : integer

The subAnim index for anim in client.

Here is an example:

-- Create a sphere and apply a bend modifier and execute

tvp=trackview.pickTrackDlg()

-- pick objects->Sphere01->Modified object->Bend->Angle

tvp.anim -- returns SubAnim:Angle

tvp.client -- returns Bend:Bend

tvp.subNum -- returns 3

tvp.name -- returns "Angle"

tvp.client[tvp.subNum] -- returns SubAnim:Angle


Picking Scene Nodes By Hit

pickObject [ message:<string> ] [ prompt:<string> ] \

[count:n|#multiple] [ filter:fn ] \

[ select:<boolean> ]

The pickObject() function lets the user pick one or more scene objects in the 3ds max viewports. It takes several optional keyword arguments. The message: argument takes a string value which is displayed in the status bar prompt line. The prompt: argument takes a string value which is displayed in the Listener window. The count: argument takes either a positive integer or the symbol #multiple to specify how many objects are to be picked (default is 1). If the count specified is greater than 1 or the value #multiple, an array is returned containing the picked objects. The symbol #multiple indicates that any number of objects can be selected and the user terminates the selection with a right mouse click or, if the Listener window has focus, any character key of the keyboard. If the ESC key is pressed while the Listener windows has focus, an #escape value will be returned. If the ESC key is pressed while a viewport has focus, selection is terminated and the selection result is returned.

If #multiple was specified, and no objects had been selected when the selection was terminated, an empty array is returned. If #multiple was not specified, and an object had not been selected when the selection was terminated, a value of undefined is returned.

The filter: function takes a MAXScript function of one argument that is called whenever the cursor is over an object in the scene and is passed that object under the cursor. It returns true if the object is eligible for picking, or false if not. Typically, the function would contain some object class testing, for example:

fn shapeFilt o = superClassOf o == Shape

which you could use like this:

pickObject prompt:"enter a shape" filter:shapeFilt

The optional keyword argument select: controls whether the picked objects become the new current selection in the 3ds max scene. If you supply true for that argument, the current selection is replaced with the objects that you pick. The default is false in which case the picker doesn't affect the selection set.


Picking Scene Nodes by Name

You can use the selectByName() function to open the standard 3ds max Select By Name dialog allowing users to pick objects which are then returned as an array of MAXScript node values. The form is:

selectByName [ title:<string> ] [ buttonText:<string> ] \

[ filter:<fn>] [ showHidden:<boolean> ] \

[ single:<boolean>]

The optional keyword arguments are interpreted as follows:

title:"string" specifies the dialog window title.

buttonText:"string" lets you specify the label text in the 'accept' button in the dialog. The default value is "Select".

filter:<fn> lets you specify a filter function that determines which objects should be displayed in the list. This is similar to the filter functions elsewhere in MAXScript. The function you supply should take one argument, which the current object being tested for inclusion and the function should return true for include, false for exclude. If you don't specify a filter, all objects are displayed. For example, the following function limits the choices to shape objects:

fn shape_filt obj = isKindOf obj Shape

showHidden:<boolean> controls whether hidden and frozen objects are eligible for display. The default value is false.

single:<boolean> controls whether single or multiple objects may be selected in the selector. The default is false, meaning multiple objects may be selected, and they are returned in an array. If single:true is specified, a single object may be selected and is returned directly, not in an array.

If the user cancels out of the dialog, the function returns the value undefined.


Picking Scene Nodes By Region

The following methods allow you to pick one or more objects based on their position in the viewports. All coordinates used in these methods are in Windows format, with the origin in the upper left. The gw.getWinSizeX() and gw.getWinSizeY() methods can be used to determine the size of the viewport in pixels. The objects to picked are filtered based on the Selection Filter specified in the 3ds max main toolbar.

boxPickNode <box2> [crossing:<boolean>]

Returns an array of the nodes within the specified rectangular region. The <box2> value specifies the corner in pixel values within the active viewport. If the crossing: parameter value is true, an object only partially in the region will be picked. If false, the object must be completely within the region to be picked. The default crossing: value is true. For example:

boxPickNode (box2 [0,0] [1000,1000])

circlePickNode <box2> [crossing:<boolean>]

Returns an array of the nodes within the specified circular region. The <box2> value specifies the center of the circle and a point on the circle in pixel values within the active viewport. If the crossing: parameter value is true, an object only partially in the region will be picked. If false, the object must be completely within the region to be picked. The default crossing: value is true. The [left, bottom] and [right, top] components of the box2 parameter value correspond to the center and radius points, respectively. The box2 parameter value needs to be set up in a specific manner, as shown in the following script:

vpCenter = (point2 (gw.getWinSizeX()) (_gw.getWinSizeY()))/2

vpQuarter = point2 (vpCenter.x/2) vpCenter.y

circleRegion = box2 0 0 0 0 -- initialize circleRegion to a box2 value

circleRegion.left = vpCenter.x -- the center of the circle

circleRegion.bottom = vpCenter.y

circleRegion.right = vpCenter.x/2 -- a point on the circle

circleRegion.top = vpCenter.y

for obj in (circlePickNode circleRegion crossing:false) do print obj.name

will print the names of all nodes completely within a circular region, where the center of the circle is the center of the viewport and the point on the circle is located one quarter of the distance from the edge to the center of the viewport.

fencePickNode <point2_array> [crossing:<boolean>]

Returns an array of the nodes within the specified fenced region. The fenced area is defined by the array of point2 values. The default crossing: value is true.


Miscellaneous Dialogs

For methods associated with the Render Effects dialog, see RenderEffect : MAXWrapper.

For methods associated with the Render Environment dialog, see Atmospheric : MAXWrapper.

exclusionListDlg()

Displays the Exclude/Include dialog used for Lights, and returns an array of the nodes 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.


MAXScript Message and Query Dialogs

These functions let you display a message box or a yes/no query dialogs from within MAXScript.

messageBox <message_string> [ title:<window_title_string> ] \

[ beep:<boolean> ]

displays a modal message box containing the message string and an OK button. The message box window title an be set with the title: keyword parameter. You can control whether a beep is made with the beep: keyword parameter, which defaults to true.

queryBox <message_string> [ title:<window_title_string> ] \

[ beep:<boolean> ]

displays a modal message box similar to the one that the messageBox() function creates, except it contains a Yes and a No button. The queryBox() function returns true if the user clicks Yes and false if the user clicks No.

yesNoCancelBox <message_string> [ title:<window_title_string> ] \

[ beep:<boolean> ]

displays a modal message box similar to the one that the messageBox() function creates, except it contains a Yes, a No, and a Cancel button. The yesNoCancelBox() function returns #yes, #no or #cancel depending on which button the user clicked to dismiss the message box.

Examples

messageBox "You shouldn't have done that"

if queryBox "Do you want to continue?" beep:false then ...

Notes

In some cases, MAXScript statements occurring after a statement containing one of the above dialog function calls may be executed before they are supposed to be. For example, if your execute:

Script:

for _t=0 to 3 do

(

messagebox "Press Me"

format "_t= %\n" _t

)

print "Should print last"

Listener will show:

Output

_t= 0

"Should print last"

"Should print last"

_t= 1

_t= 2

_t= 3

And the MessageBox will be displayed 4 times, once each time before the value of _t is printed to Listener.

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.

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 Defining Macro Scripts for information on creating Macro Scripts. The Macro Script functions are:

macros.load [ <path_name_string> ]

Loads all of the Macro Script definition (.mcr) files in the current UI directory path, or in directory path specified by <path_name_string>. You can get the current UI directory path with the function:

local ui_dir = cui.getDir ()

macros.new <name_string> <category_string> <toolTip_string> \

<buttonText_string> <body_string>

Creates a new Macro Script with the specified name and category. Returns an Integer Macro Script ID value that uniquely identifies the new Macro Script. See Defining Macro Scripts for a description of Macro Script definitions.

macros.run <category_string> <name_string>

macros.run <macro_id_integer>

Executes the specified Macro Script. The Macro Script is identified by either its category and name, or by its unique Macro Script ID value.

macros.edit <category_string> <name_string>

macros.edit <macro_id_integer>

These methods will open the Macro Script definition (.mcr) file that defines the specified Macro Script in a script Editor window. The Macro Script is identified by either its category and name, or by its unique Macro Script ID value.

examples:

macros.load "f:/gametools/macros"

macros.edit "objects" "box"

macros.run 132

macros.run "modifiers" "bend"


3ds max System Directories

The following methods allow you to access the 3ds max system directories:

GetDir <filetype_name>

Returns as a string the directory specified in the Customize > Configure Paths dialog for the specified file type. The valid <filetype_name> values are:

#autoback

#drivers

#export

#expression

#font

#help

#image

#import

#matlib

#maxroot

#maxstart

#plugcfg

#preview

#scene

#scripts

#sound

#startupScripts

#ui

#vpost

The following functions let you get, add or delete Bitmap and XRef paths, corresponding to the Bitmaps and XRefs tabs in the Configure Paths dialog in 3ds max. Any changes made through these functions are immediately reflected in the 3dsmax.ini file and so are persistent.

mapPaths.add <path_string>

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

mapPaths.count()

Returns the number of Bitmap search paths defined.

mapPaths.get <index>

Returns the indexed Bitmap search path as a string. The index is 1-based.

mapPaths.delete() <index>

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

xrefPaths.add <path_string>

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

xrefPaths.count()

Returns the number of XRef search paths defined.

xrefPaths.get <index>

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

xrefPaths.delete <index>

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


3ds max Scene File Properties

The File Properties can be accessed in MAXScript using the methods described in this topic. The File Properties are organized into three sets. These sets do directly does not correspond to the three pages in File Properties dialog. The three sets are:

#summary

This set contains the Title, Subject, Author, Keywords, Comments fields from the Summary page.

#contents

This set contains the Manager, Company, Category and an array of all headers from the Contents page like General, Mesh Totals etc. Note that the Contents page contents are only update when the file is saved. You can perform a max hold to perform a scene hold, which causes the file to be saved and the Contents page contents to be updated.

#custom

This set contains all the fields from the Custom page.

The following methods are used to access the above sets. <set_name> can be any of the values from above.

fileProperties.getNumProperties <set_name>

Returns the number of properties in the given set. For example:

numProps=fileProperties.getNumProperties #summary

fileProperties.getPropertyName <set_name> <index>

Returns as a string the property name of the given index. The index is 1-based. For example:

nameProp=fileProperties.getPropertyName #summary 1

fileProperties.getPropertyValue <set_name> <index>

Returns the property value of given index. The value type can be one of the following four types of values currently supported by 3ds max in the File Properties dialog. The values in bracket are the MAXScript equivalent value type.

Property Value Types:

Text [String]

Date [String] - contains the date eg:"03/23/99"

Number [Integer or Float based on actual value]

Yes or No [Boolean]

Headers [Array of strings]

Headers are items like General, Mesh Totals, etc. that appear in contents page. For example, an array of headers from contents page obtained using:

fileproperties.getPropertyValue #contents 1

will return

#("General", "Mesh Totals",…)

fileProperties.getItems <header_string>

Returns an array of strings containing all the items under the given header. For example,

fileProperties.getItems "Mesh Totals"

might return

#("Vertices: 488", "Faces: 968")

fileProperties.findProperty <set_name> <prop_name_string>

Given the set name and property name string, will return the index of the property if found, 0 if not found. For example:

fileProperties.findProperty #custom "BoolVal"

fileProperties.addProperty <set_name> <prop_name_string> \

<prop_value> [#date]

Adds a new property with the property name and property value to the specified set. The property values can be any of the types previously described except an Array as you cannot add anything to contents page.

If string containing a date is passed then the optional #date argument has to be passed for it to be added as a date value. For example,

fileProperties.addProperty #custom "DateVal" "03/23/99" #date

will add a date property named DateVal to the custom page.

fileProperties.deleteProperty <set_name> <prop_name_string>

Delete the property indicated by <prop_name_string> in the specified set.

Following is an example of printing all the File Properties in an hierarchial fashion for the current scene.

Example:

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

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

)

)


MAX Commands

3ds max Commands

The general syntax for 3ds max commands is:

max <command_name>

MAXScript allows you to invoke 3ds max menu and toolbar commands from within scripts using the max construct. For example:

max file open

max unhide all

max hold

max time play

The keyword max is followed by one or more words that describe the command. The available commands can be displayed using the '?' character in a partial max command:

max time ? -- show all the time-related commands

max sel ? -- show all the commands with 'sel' in them as a substring

max ? -- show all the commands (there are a lot!)

The max command always returns the system value ok.

Note: The max spacebar max command appears to do nothing when invoked from the Listener window, because the spacebar command is window-specific and only locks selections in the active window. Because it is the Listener window that is active, 3ds max effectively ignores this command.
3ds max Command Name | Command description
max ? | Displays all max commands to listener
max accel pan | Activates viewport Pan mode
max acthomegrid 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
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
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 | Toggles display of main toolbar
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
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
max swap layouts | No operation – no A/B layout any more
max texture correct | Toggles viewport Texture Correction
max time back | Sets time slider to previous frame or keyframe (Previous Frame/Previous Key)
max time config | Displays Time Configuration dialog
max time end | Sets time slider to end frame (Go to End)
max time forward | Sets time slider to next frame or keyframe (Next Frame/Next Key)
max time play | Plays animation
max time start | Sets time slider to start frame (Go to Start)
max toggle key mode | No operation
max toggle keyboard shortcuts | Toggles Plug-in Keyboard Shortcut Toggle
max toggle ik | Toggles IK Toggle
max toggle sound | Toggles Active in Audio group of Sound Options dialog
max tool animmode | Taggles Animate button
max tool center | Cycles through transform centers – Pivot Point, Selection, Transform
max tool dualplanes | Toggles state of Use Dual Planes in Preference Settings dialog, Viewports tab.
max tool hlist | Activates Select by Name – displays Select Objects dialog
max tool maximize | Maximizes/Minimizes active viewport
max tool x | Activates Restrict to X
max tool xy | Activates Restrict to XY
max tool y | Activates Restrict to Y
max tool z | Activates Restrict to Z
max tool zoom | Activates Zoom/Dolly mode
max tool zoomall | Activates Zoom All
max tool zoomextents | Activates Zoom Extents
max tool zoomextents all | Activates Zoom Extents All
max tool zoomregion | Activates Zoom Region/FOV/Falloff mode
max trajectories | Toggles trajectory display for selected objects
max treeview | Activates Track View/Open Track View – displays Track View dialog
max truck | Activates Pan/Truck mode
max tti | Activates Tools/Transform Type-In – display Transform Type-In dialog
max undo | Performs undo operation
max unfreeze all | Unfreezes all objects. Same as clicking Unfreeze All in Display panel.
max unfreeze by hit | Activates Unfreeze by Hit mode. Same as clicking Unfreeze by Hit in Display panel.
max unfreeze by name | Displays Unfreeze Objects dialog. Same as clicking Unfreeze by Name in Display panel.
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
max zoom in 2x | 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


3ds max File Loading and Saving

The following methods are used to load, save, merge, import, and export 3ds max scenes.

loadMaxFile <filename_string>

Returns true if the file was found and loaded successfully.

mergeMAXFile <filename_string> [ <name_array> ] [ #prompt ] \

[ [ #select ] #noRedraw ] \

[ #deleteOldDups | #mergeDups | #skipDups | #promptDups ]

All arguments are optional except the initial file name. The flag arguments can be specified in any order. The arguments details are as follows:

<name_array>

An optional array of names or strings identifying the objects in the source scene file to be merged; all objects are merged if not specified.

#prompt

If specified causes the standard merge dialog to be opened.

#select

If specified causes the newly merged objects to be selected when merged.

#noRedraw

If specified causes the screen redraw to be delayed in case you want to call mergeMAXFile several times and delay the redraw until after the last file merge.

#deleteOldDups

Deletes existing scene objects with the same names as incoming objects, equivalent to a replace.

#mergeDups

Ignore name conflicts, merge anyway resulting in possibly duplicated names.

#promptDups

Throw up the duplicates resolution dialog for the user to choose.

Returns true if the file was found and loaded successfully.

If you don't specify a full path name, the file is looked for in the 3ds max scene directory, then in the 3ds max executable directory, and then in the PATH environment directories.

getMAXSaveFileName filename: <seed_filename_string>

Displays standard 3ds max file save dialog, returns file name or value 'undefined' if canceled.

getMAXOpenFileName filename: <seed_filename_string> dir:<seed_directory_string>

Displays standard 3ds max file open dialog, returns file name or value 'undefined' if canceled.

getMAXFileObjectNames <max_filename_string>

Returns an array of names, one for each of the names of the objects in the given 3ds max file. This provides a way to get a preview list of the objects in another scene file (by name) to set up user selection of the objects to be merged under script control using the mergeMAXFile() function, for example.

Example:

p=[1000,1000,1000]

for i = 1 to 5 do box pos:(random p -p) -- create some boxes

savemaxfile "mergetest.max" -- save to file

for obj in objects do obj.name = "_"+obj.name -- rename the boxes

objects.pos += [0,-1000,0] -- move them off to the side

fobj_names = getmaxfileobjectnames "mergetest.max" -- get the object names from the file

deleteitem fobj_names 3 -- delete the third name from the array

mergemaxfile "mergetest.max" fobj_names #select -- merge in the objects and select them

selection.count -- should be 4

objects.count -- should be 9

saveMaxFile <filename_string>

Saves the scene to the current 3ds max scene directory if there is no explicit directory path on the supplied file name. If no filename extension is specified, ".max" is automatically appended to the filename.

holdMaxFile()

Equivalent to the 3ds max Edit > Hold operation.

fetchMaxFile()

Equivalent to the 3ds max Edit > Fetch operation.

importFile <filename_string> [ #noPrompt ]

Lets you import files using any of the import plug-ins that are available. The kind of file imported is determined by the file name suffix such as DFX for .dxf, 3DS DOS for .3ds, etc.

The #noPrompt flag prevents any configuration or control dialogs from being displayed in which case the default configuration is used.

exportFile <filename_string> [ #noPrompt ]

Lets you export files using any of the export plug-ins that are available. The kind of file exported is determined by the file name suffix such as DFX for .dxf, 3DS DOS for .3ds, etc.

The #noPrompt flag prevents any configuration or control dialogs from being displayed in which case the default configuration is used.

saveNodes <node_collection> <filename_string>

Creates a new .max scene file with the given name and stores the node collection to it. The <node_collection> argument can be a single node, an array of nodes you gathered, a wild-card path name, one of the built-in objects sets such as selection or lights, or a <node>.children array. If no filename extension is specified, ".max" is automatically appended to the filename.

checkForSave()

If the scene has been modified since the last file save (if any), calling this function displays the message box prompting the user that the scene has been modified and requests to save. Function returns false if the user cancels out of the save, true otherwise.

See also

External File Methods

File Name Parsing

Standard Open and Save File Dialogs


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 Bitmap Values.

enumerateFiles [ <maxwrapper_obj> ] <function> [ <arg> ] \

[ #inactive ] [ #videoPost ] [ #render ] [ #missing ] \

[ #localOnly ]

Lets you run through all the bitmap files currently used in the scene or in an individual object. You can filter this so it just gives you those for video post or the renderer or the ones that are inactive or missing.

The enumerator works by calling a function you give it once for each of the file names it finds corresponding to the filters switches and other arguments you set.

The only required argument is the <function> argument. The details are:

<maxwrapper_obj>

An optional 3ds max object, such as a node or a material. Supplying this argument causes the enumerator to only consider files associated with this object. See the #localOnly switch for more info.

<function>

The function to be called for each file found. It should be a function of one or two arguments, the first one is the string file name supplied by the enumerator. See example below.

<arg>

If specified is passed to the <function> as its second argument by the enumerator. This is useful if you have a general purpose enumerator function that can be conditioned by the argument you pass in on a particular enumeration, or if you want to pass in an array that the found names should be appended to.

#inactive

Include the inactive files.

#videoPost

Include the files used in video post.

#render

Include the files used during rendering.

#missing

include files that are missing in the file system

If you don't specify any of the above filter flags, all the files are enumerated.

#localOnly

use in conjunction with the <maxwrapper_obj> argument. If specified, limits the enumeration to those files used directly in the object, if not then any referenced objects are scanned.

For example:

function get_names name a = append a name

files = #()

enumerateFiles get_names files #missing

The following script will print out a sorted list of all the bitmap files used in the current scene file:

Example:

(

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)

)

By replacing line 8 with

enumeratefiles addmap #missing

only the missing bitmap files will be printed.

See also

External File Methods

File Name Parsing

Standard Open and Save File Dialogs


XRef Files

See XRefObject and XRefScene for information on XRef Object and XRef Scene files.


Text File Input and Output

See FileStream Values for information on creating, opening, closing, and accessing external text files.


Standard Open and Save File Dialogs

The following methods display the standard 3ds max file open, file save, or folder selection browser dialog:

getOpenFileName [ caption:<title> ] \

[ filename:<seed_filename_string> ] \

[ types:<description1>|<pattern1>|<description2>|<pattern2>|...| ]

getSaveFileName [ caption:<title>] \

[ filename:<seed_filename_string> ] \

[ types:<description1>|<pattern1>|<description2>|<pattern2>|...| ]

Both functions return a fully-specified file path name or undefined if the user cancels out. The types: parameter lets you specify custom file types and suffixes for the file type drop-down list in the open and save dialogs. You supply a string for this argument that is formatted in a special way, as follows:

"<description1>|<pattern1>|<description2>|<pattern2>|...|"

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

External File Methods

File Name Parsing


File Name Parsing

filenameFromPath <filename_string>

Returns the file name and extension of a full file name, useful for labeling file buttons in rollout panels.

getFilenamePath <filename_string>

Returns the directory path part of a full file name.

getFilenameFile <filename_string>

Returns the file name part of a full file name.

getFilenameType <filename_string>

Returns the type extension part of a full file name.

doesFileExist <filename_string>

Returns true if the file exists, false otherwise

Examples:

file="g:\\subdir1\\subdir2\\myImage.jpg"

filenameFromPath file -- returns: "myImage.jpg"

getFilenamePath file -- returns: "g:\subdir1\subdir2\"

getFilenameFile file -- returns: "myImage"

getFilenameType file -- returns: ".jpg"

See also

Filestream Values

External File Methods

Standard Open and Save File Dialogs


External File Methods

getFiles <wild_card_filename_string>

Returns an array of file names that match the given wild-card path name. The following example gets an array of all the .max scene files in c:\foo and then loops over the array, opening each file and printing the objects in each:

files = getFiles "c:\\foo\\*.max"

for f in files do (loadMAXFile f; print objects)

getFiles() can also be used to determine if a file exists. For example, the following function will return true if the specified file name exists:

fn existFile fname = (getfiles fname).count != 0

getDirectories <wild_card_directory_name_string>

Returns an array of directory paths that match the given wild-card directory path name.

makeDir <directory_path_string>

Creates a new directory with the given name. Returns true on success, false on failure.

deleteFile <filename_string>

Deletes the named file. Fails if the file is open in MAXScript. Returns true on success, false on failure.

renameFile <old_filename_string> <new_filename_string>

Renames the old file to the new file. This can also be used to move a file between directories. Fails if new file already exists or if the old file is open in MAXScript. Returns true on success, false on failure.

copyFile <existing_filename_string> <new_filename_string>

Copies the existing file to the new file. Fails if the new file already exists, the new file cannot be created, or the existing file is open in MAXScript. Returns true on success, false on failure.

getFileAttribute <filename_string> <attribute>

setFileAttribute <filename_string> <attribute> <boolean>

Get and set the attributes associated with a file. The get function returns true or false depending on the state of the specified attribute, the set function sets the state of the individual attribute specified (leaving other attributes as they were). The valid <attribute> values are:

#readOnly

#hidden

#system

#directory

#archive

#temporary

#normal

getFileModDate <filename_string>

Returns a String value containing the modification date for the specified file, for example "1/29/99 1:52:05 PM".

getFileCreateDate <filename_string>

Returns a String value containing the creation date for the specified file.

getFileVersion <filename_string>

Returns the file and product version for the specified file, or unknown if this data is not specified in the file. This data is typically specified only for executable and application extension (i.e., .dll) files. For example:

GetFileVersion "g:\\3dsmax25\3dsmax.exe"

returns "2,5,0,0 2,5,0,0"

Examples:

for f in getFiles "3dsmax\\maps\\*.jpg" do deleteFile f

for d in getDirectories "D:\\foo\\*" do

for f in getFiles (d + "*.*") do

copyFile f ("C:\\temp\\" + getFilenameFile f + getFilenameType f)

if (getFiles "foo.max").count == 0 then print "File missing"

See also

Filestream Values

File Name Parsing

Standard Open and Save File Dialogs


Encrypted Files

encryptFile <in_filename_string> <out_filename_string> <key_integer>

Creates an encrypted copy of the file named by <in_filename_string> using the integer supplied as a key, naming the encrypted file <out_filename_string>.

openEncryptedFile <filename_string> <key_integer>

Opens the encrypted file using the given integer key and returns a FileStream value that you can then do read calls on, exactly as you can on FileStreams returned from the openFile() function.

encryptFile() and openEncryptedFile() let you encrypt a text file with your own key and open an encrypted file via a key for reading. Among other things, you can use this to write and read an encrypted file containing a hardware lock ID for doing authorization-based piracy protection.

For example, here's some code that creates an encrypted lock ID file in some authorization process:

f = createFile "lock.tmp"

format "%" hardwareLockID to:f

close f

encryptFile "lock.tmp" "lock.dat" 5476557

deleteFile "lock.tmp"

The following code can be used to read and check the lock ID (obviously, all this is only safe if the creation and checking scripts are themselves encrypted):

f = openEncryptedFile "lock.dat" 5476557

id = readValue f

close f

if id != hardwareLockID then

(

message "Lock ID's don't match"

return 0

)


Accessing INI File Keys

The following methods allow you to read and write key values in .INI files.

getINISetting <filename_string> <section_string> <key_string>

Reads an INI setting from the specified file. Within the file, the section identified by <section_string> is located, and then the key specified by the <key_string> is located. The value assigned to this key is then returned as a string. If the specified file, section, or key is not found, a null string is returned. For example:

GetINISetting "c:\\3dsmax2\\3dsmax.ini" "Directories" "Scenes"

If the specified file, section, or key is not found, a null string is returned.

setINISetting <filename_string> <section_string> <key_string> <key_value_string>

Sets an INI setting in the specified file. Returns a value of true if the key value was written to the file, false if the key was not written. Within the file, the section identified by <section_string> is located, and then the key specified by the <key_string> is located. The <key_value_string> is then assigned to this key. For example:

setINISetting "c:\\3dsmax2\\3dsmax.ini" "Directories" "Scenes" "c:\\3dsmax\\scenes"

If the specified file, section, or key is not found, a new file, section, or key is created.

If the specified file is read-only, or the file is open in MAXScript, the key value is not written to the file.


Custom User Interface Files

The following methods provide access to Custom User Interface (CUI) files. The CUI functions are in a structure package named cui.

cui.getDir()

Returns the directory of the currently active CUI file as a string.

cui.getConfigFile()

Returns the currently active CUI file name as a string.

cui.setConfigFile <filename_string>

Sets the currently active CUI file to the specified file name.

cui.saveConfig()

Saves the current CUI configuration data to the active .cui file

cui.saveConfigAs <filename_string>

Saves current CUI configuration data to the specified file. The specified file is made the current CUI file.

cui.loadConfig <filename_string>

Loads the CUI configuration data from supplied file. The specified file is made the current CUI file.

Note: The Customize/Load Custom UI Scheme menu item is implemented as a macroScript. This macroScript is called macro_uischeme.mcr in the \ui\macroscripts directory. cui.loadConfig is only part of what needs to be done to switch over to a new UI scheme. The aforementioned macroScript will guide you through the other actions that also need to be performed.


ImgTag

ImgTag <name> [caption] [tooltip:<string>] [style:<key>] [bitmap:<bitmap>] [opacity:<float>] [transparent:<color>]

Properties

<ImgTag>.tooltip String default:""

<ImgTag>.bitmap Bitmap default:undefined

Current image being displayed.

<ImgTag>.style Key default:#bmp_stretch

Way the bitmap will be displayed in the control.

Can be one of the following:

#bmp_stretch

#bmp_tile

#bmp_center

<ImgTag>.opacity float default:0.0

Overall opacity of the image, can range from 0.0 to 1.0

<ImgTag>.transparent color default:(color 0 0 0)

The RGB color in the source bitmap to treat as transparent.

Note: Opacity and transparent properties only have an effect in W2K. These do not have an effect in NT.

Events

on <ImgTag> mousedown do <expr>

Called when the left mouse button is pressed down.

on <ImgTag> mouseup do <expr>

on <ImgTag> click do <expr>

Called when the left mouse button is released.

on <ImgTag> dblclick do <expr>

Called when the left mouse button double clicked.

on <ImgTag> mouseover do <expr>

Called when the mouse is moved into the image area.

on <ImgTag> mouseout do <expr>

Called when the mouse is moved out of the image area.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types


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

Time Change Callback Mechanism

Viewport Redraw Callback Mechanism

RenderEffect Progress Callback Mechanism

General Event Callback Mechanism

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 Scripted Right-Click Menus for more information.


Change Handlers and When Constructs

Change Handlers are used to detect when certain types of user events are performed on objects in the scene, allowing you to write scripts that respond to user operations like object moves, vertex edits, object deletions, name changes, etc.. Change Handlers are applied to individual MAXWrapper objects and specify an attribute to monitor for that object and an expression to evaluate when that attribute changes. Example attributes that can be monitored are geometry, name, transform, and parameters. Change Handlers are not stored in a 3ds max scene.

The ChangeHandler : Value class instances represent change handler setups. ChangeHandler values are created using the when construct. Each time a when construct is executed, it creates and returns a new ChangeHandler instance. You should store this ChangeHandler value in a variable or array so that you can dismiss the handler when it is appropriate to do so.

The when construct defines a change handler function for a certain type of event on one or more objects. The system then automatically calls this function whenever the event occurs. The syntax of the when construct has two forms as follows:

when <attribute> <objects> change[s] [ id:<name> ] \ [handleAt:#redrawViews|#timeChange] \ [ <object_parameter> ] do <expr>

when <objects> deleted [ id:<name> ] \ [handleAt:#redrawViews|#timeChange] \ [ <object_parameter> ] do <expr> \

In the first form, the <attribute> can be one of:

topology

geometry

name[s]

transform

select

parameters

subAnimStructure

controller

children

These specify the attribute of the given object(s) to be tracked for change (see below for more details).

The second form tracks object deletion by the user or other scripts. For object deletion events, the handler is called after the object is deleted, so you cannot perform any 3ds max operations on it. This is typically used if you have tables or other structures containing MAXScript object values and you want to remove deleted objects from them as the user modifies the scene.

In both forms, the <objects> argument can be one of the following:

  • a single 3ds max object, such as a scene node, controller, modifier, or material, etc.

  • one of the object sets, such as 'selection', or 'cameras', etc.

  • a wild-card pathname like $foo*.

  • an array of 3ds max objects.

If more than one object is specified, the handler is called each time the given attribute of any of the objects is signaled as changed by the 3ds max core.

The optional id: parameter specifies an ID for one or more handlers as a name literal. The ID name can later be used to delete the handler and, if the same name is given to several handlers, they can be deleted as a group.

The optional handleAt: parameter signals that the change handler expression should not be executed immediately upon notification, but delayed until the either the 3ds max viewports are redrawn (#redrawViews) or current 3ds max animation time is changed (#timeChange). Delaying the processing of the change handler expression is highly recommended, as described in the Caution section below. An example usage of the handleAt: parameter is:when select $ changes id:#foo handleAt:#redrawViews do ...

The optional <object_parameter> lets you specify the name of a parameter variable that will be accessible in the do <expr> and will hold the actual object that has changed. You typically specify this parameter name if the handler will respond to changes in many objects, so you can determine which one has changed. The <expr> can be a single expression or block expression.

Examples

when transform $box01 changes do

$box02.pos = $box01.pos + delta

when names selection change obj do update_name_table obj

when #($foo, $baz, $bar) deleted obj do

(

messageBox "Warning!"

deleteItem obj_table (findItem obj_table obj)

)

The change attributes are interpreted as follows:

topology

Signaled when the topology of an object changes in the Modify panel, such as via a mesh smooth, optimize, or vertex delete.

geometry

Signaled when the geometry of an object changes, such as by moving a vertex or via an animated modifier.

name or names

Signaled when the name of an object is changed if this occurs because a user edits the name in one of the 3ds max command panels. The handler is called repeatedly with each character that is changed.

transform

Signaled when the transform of an object is changed, such as by a move, rotate, or scale.

select

Signaled when a scene node moves into or out of the current selection set. You should interrogate the <node>.isSelected property to determine the new state.

parameters

Signaled when any parameters are changed in the object. This is something of a catch all, because the core signals this event in many situations.

subAnimStructure

Signaled when the dynamic subAnim structure changes, such as when a new vertex becomes animated in an editable mesh, or when a new controller is added to a list controller. Also called when subAnims are reassigned, for example, when a material is changed in an object.

controller

Signaled when a new controller is assigned to one of the object's tracks.

children

Signaled when an object has immediate children added or removed.

You can use the following two methods for deleting change handlers:

deleteChangeHandler <change_handler>

deletes specified change handler. change_handler is the value returned by a when construct.

deleteAllChangeHandlers [ id:<name> ]

If optional id: parameter is not specified, deletes all change handlers. If optional id: parameter is specified, deletes all change handlers with the specified id. For example:

deleteAllChangeHandlers id:#foo

For efficiency reasons, you don't want irrelevant change handlers running in the background, so it is essential that you delete those that you no longer need.

Special Considerations

  • If a runtime error occurs in the body of a change handler while it is being executed, an error message is displayed and that handler is permanently disabled.

  • If all of the objects being tracked by a change handler are deleted, the change handler is also deleted.

  • The do <expr> change handler code is executed in a special context and not in the context of the code that created it. This means that the <expr> code cannot contain references to local variables in outer code nestings surrounding the when, since those variables are on an execution stack that does not exist at the time the when handler is called. The compiler detects any illegal references to outer locals and generates a compiler message. An important exception to this is utility and rollout panel locals, such as local functions, rollout variables and nested rollouts. You can refer to them in change handler code inside rollout code as they are associated directly with their rollout or utility object.

  • Change handlers are called only for user initiated events, and not for changes resulting from a change in controller values. For example, a change handler on the transform attribute of a node would be called when the user moves the node. If the position of the node is animated, and you play back the animation, the transform attribute change handler is not called.

  • 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.


Time Change Callback Mechanism

You can register one or more functions to be called whenever the current 3ds max animation time is changed, such as when the user drags the time slider or plays the animation. The following methods let you register and unregister these callbacks:

registerTimeCallback <fn>

unRegisterTimeCallback <fn>

You can register as many functions as you like. Each one is individually called whenever the time changes. The functions you register must take no arguments. They can access the updated current time through the MAXScript system variable currentTime.

Example

fn time_p = print currentTime

registerTimeCallback time_p

In the above example, the registered function causes the current time to be printed in the Listener window whenever the user moves the time slider or plays the animation.

Special Considerations

  • If a runtime error occurs in a callback function while it is being executed, an error message is displayed and that callback function is permanently disabled.

  • The time callback is not called during rendering, even if multiple frames are rendered.

  • The registered function is executed in a special context and not in the context of the code that created it. This means that the function cannot contain references to local variables in outer code nestings surrounding the function definition since those variables are on an execution stack that does not exist at the time the function is called. An important exception to this is utility and rollout panel locals, such as local functions, rollout variables and nested rollouts. You can refer to them in change handler code inside rollout code as they are associated directly with their rollout or utility object.

  • Note that it is the function value that is being registered, not the function name or global variable. This means that redefining the same-named function after registering it does not change the callback. You either need to unregister, re-define the function and then register it again, or make the registered function an intermediary which calls another function, for example:

fn time_cb = print currentTime

fn tcb = time_cb()

registerTimeCallback tcb

In this case, the registered callback function, tcb, calls the real call back, time_cb, (by referencing the global variable it is defined in), meaning you can redefine time_cb() as often as you need and the callback will always invoke the latest definition. This is a useful technique to employ while you are developing and debugging a callback.

  • Callback functions remain registered after loading a new file or performing a 3ds max reset.


Viewport Redraw Callback Mechanism

You can register one or more functions to be called whenever the 3ds max viewports are redrawn. The following methods let you register and unregister these callbacks:

registerRedrawViewsCallback <fn>

unRegisterRedrawViewsCallback <fn>

You can register as many functions as you like. Each one is individually called whenever the viewports are redrawn. The functions you register must take no arguments.

Example

fn redrawviews_p = print "Viewports Redrawn"

registerRedrawViewsCallback redrawviews_p

In the above example, the registered function causes the string "Viewports Redrawn" to be printed in the Listener window whenever the 3ds max viewports are redrawn.

Special Considerations

  • If a runtime error occurs in a callback function while it is being executed, an error message is displayed and that callback function is permanently disabled.

  • The registered function is executed in a special context and not in the context of the code that created it. This means that the function cannot contain references to local variables in outer code nestings surrounding the function definition since those variables are on an execution stack that does not exist at the time the function is called. An important exception to this is utility and rollout panel locals, such as local functions, rollout variables and nested rollouts. You can refer to them in change handler code inside rollout code as they are associated directly with their rollout or utility object.

  • Note that it is the function value that is being registered, not the function name or global variable. This means that redefining the same-named function after registering it does not change the callback. You either need to unregister, re-define the function and then register it again, or make the registered function an intermediary which calls another function, for example:

fn redrawviews_cb = print currentTime

fn rvcb = redrawviews_cb()

registerRedrawViewsCallback rvcb

In this case, the registered callback function, rvcb, calls the real call back, redrawviews_cb, (by referencing the global variable it is defined in), meaning you can redefine redrawviews_cb() as often as you need and the callback will always invoke the latest definition. This is a useful technique to employ while you are developing and debugging a callback.

  • Callback functions remain registered after loading a new file or performing a 3ds max reset.


Miscellaneous Functions

freeSceneBitmaps()

Frees up all the memory used by the image file bitmap caches. This is useful if memory is fragmented with a lot of different bitmaps and you want to have just the ones currently active reloaded.

rescaleWorldUnits <factor> [ #selOnly ]

This method provides functionality similar to that of Rescale World Utility plug-in in 3ds max. <factor> is the factor the objects should be scaled by. If #selOnly is specified then only the selected objects are scaled.

IsNetServer()

Returns true if 3ds max is operating in network rendering mode and false if operating in normal interactive mode.

loadDllsFromDir <directory_path_string> <filename_wildcard_string>

Load all the plug-ins found in the specified directory. The directory_path_string must be terminated with a '\'. For example:

LoadDllsFromDir "f:\\maxsdk\\plugin\\" "*.dlc"

maxVersion()

Returns an Array with three integers like #(3000, 6, 0) with 3ds max release number, max API number, revision number of the SDK.

swap <destination> <destination>

Takes two valid assignment destinations (property, array index, or variable) as arguments and swaps their values. For example:

swap myMaterial.diffuseMap.map1 myMaterial.diffuseMap.map2


Pausing Script Execution

The sleep function lets you pause script execution for a given amount of time.

The form is:

sleep <time_in_seconds>

The time argument is a floating point number of seconds to sleep.

Note that the sleep time is not guaranteed to be extremely accurate. You can interrupt a sleep with the ESC key which halts all execution or with the SPACE bar which simply causes the sleep function to terminate and the script to continue executing. In both cases, you may need to hold the key down for up to half a second for MAXScript to respond.


Time Stamping

The timeStamp() function gives time-of-day in milliseconds.

The form is:

timeStamp()

The function returns the number of milliseconds since 00:00 hours that day. This is useful for timing operations (presuming you are not timing across midnight.)

Example:

start = timeStamp()

process_mesh() -- do some big job

end = timeStamp()

format "Processing took % seconds\n" ((end - start) / 1000.0)


Controlling the Renderer

You can use the render() function to invoke the 3ds max renderer. It can take many optional parameters to control the rendering.

render

[ camera: <camera_node> ]

Defaults to active viewport.

[ frame: <number> | #current ]

Defaults to #current.

[ framerange: <interval> | #active ]

[ fromframe: <number> ]

[ toframe: <number> ]

[ nthframe: <number> ]

Defaults to unsupplied, and the frame value controls which frames to render.

[ outputwidth: <number> ]

Defaults to current render width.

[ outputheight: <number> ]

Defaults to current render height.

[ outputSize: <point2> ]

An alternative way to specify the output size of the rendered image. The point2 value is in the form: [width,height]

[ pixelaspect: <number> ]

Defaults to 1.0.

[ renderhiddenobjects: <boolean> ]

Defaults to current renderer Render Hidden Objects state.

[ superblack: <boolean> ]

Defaults to current renderer Superblack state.

[ force2sided: <boolean> ]

Defaults to current renderer Force 2 Sided state.

[ renderatmosphericeffects: <boolean> ]

Defaults to current renderer Render Atmospheric Effects state.

[ renderfields: <boolean> ]

Defaults to current renderer Render Fields state.

[ fieldorder: #odd | #even ]

Defaults to current renderer preferences Field Order state.

[ outputfile: <string> ]

The frame number is appended to the filename if the file image type is a single image type (.bmp, .jpg, .tga, etc.), and a frame range is being rendered. Defaults to rendering to just the virtual frame buffer.

[ vfb: <boolean> ]

Defaults to current renderer Show VFB state.

[ netrender: <boolean> ]

Defaults to current renderer Net Render state.

[ renderer: #draft | #production]

Allows the selection of draft or production renderer. By default, the currently selected renderer is used.

[ renderType: #normal | #region | #regionCrop | #blowup | #selection ]

[ region: #(left,top,right,bottom) ]

Provides control over the type of rendering, corresponding to the Render Type menu in the 3ds max toolbar. If #region or #blowUp is selected, the region: parameter may be used to override the currently set regions for the active viewport, specified as pixel coordinates relative to the top-left corner in the bitmap (VFB). Note that #region and #blowUp can only be selected for an active viewport rendering. An error will be reported if they are specified for a camera rendering. Defaults to #normal.

[ to: <bitmap> ]

Specifies an existing bitmap to render into. The render() function takes image size and other parameter settings from the existing bitmap. If not supplied, a new bitmap is created and returned by the render() function.

[ channels: <array_of_channel_names> ]

Specifies which g-buffer channels should be created during the rendering. For example:

bm = render camera:$cam2 channels:#(#zDepth, #coverage, #objectID)

causes $cam2 to be rendered into a new bitmap that will contain z-depth, pixel coverage and object g-buffer ID channels. The channels: argument must always be an array of channels identifiers, chosen from the following:

#zDepth

#matID

#objectID

#UVCoords

#normal

#unClamped

#coverage

#node

#shaderColor

#shaderTransparency

#velocity

#weight

Defaults to no g-buffer channels.

[ aperture: <float> ]

Defaults to current renderer Aperture Width value.

[ ditherTrueColor: <boolean> ]

Defaults to current rendering preferences Dither True Color state.

[ ditherPaletted: <boolean> ]

Defaults to current rendering preferences Dither Paletted state.

[ videocolorcheck: <boolean> ]

Defaults to current renderer Video Color Check state.

[ renderPAL: <boolean> ]

Defaults to current rendering preferences Video Color Check NTSC/PAL state. If true, and video color checking is enabled, PAL video color checking is performed.

[ superBlackThreshold: <integer> ]

Defaults to current rendering preferences Super Black Threshold value.

[ maxPixelSize: <float> ]

All correspond to items in the 3ds max Render Scene setup dialogs.

The following are also available if the 3ds max standard scanline renderer is being used:

[ antiAliasing: <boolean> ]

Defaults to current renderer Anti-Aliasing state.

[ antiAliasFilterSize: <float> ]

Defaults to current renderer Anti-Aliasing Filter Size value.

[ antiAliasFilter: <filter> ]

Defaults to current renderer Anti-Aliasing filter.

[ enablePixelSampler: <boolean> ]

Defaults to the current renderer Global SuperSampling state. This state is true if Disable all Samplers is checked, otherwise false.

[ mapping: <boolean> ]

Defaults to current renderer Mapping state.

[ shadows: <boolean> ]

Defaults to current renderer Shadows state.

[ autoReflect: <boolean> ]

Defaults to current renderer Auto-Reflect/Refract and Mirrors state.

[ forceWireframe: <boolean> ]

Defaults to current renderer Force Wireframe state.

[ wireThickness: <float> ]

Defaults to 1.0.

[ filterMaps: <boolean> ]

Defaults to current renderer Anti-Aliasing Filter Maps state.

[ objectMotionBlur: <boolean> ]

Defaults to current renderer Object Motion Blur Apply state.

[ objectBlurDuration: <float> ]

Defaults to 0.5.

[ objectBlurSamples: <integer> ]

Defaults to 10.

[ objectBlurSubdivisions: <integer> ]

Defaults to 10.

[ imageMotionBlur: <boolean> ]

Defaults to current renderer Image Motion Blur Apply state.

[ imageBlurDuration: <float> ]

Defaults to 0.5.

[ autoReflectLevels: <integer> ]

Defaults to 1.

You can invoke the renderer and have it do one or more of four things with the rendered output:

  • Display it in a virtual frame buffer (the default), controlled with the vfb: parameter.

  • Store the rendering in an image file by supplying an outputfile: parameter. The type of image file to be created is determined from the file suffix you specify.

  • Return the result as a MAXScript Bitmap value that you can perform Bitmap operations on (see the Bitmap Values 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.

Note: 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

Executing External Commands and Programs

MAXScript provides two methods for executing external programs. DOSCommand() takes a DOS command as a string and send it to the system for execution. It has the form:

DOSCommand <command_string>

Examples:

DOSCommand "delete c:\\temp\\foo.dat"

DOSCommand ("copy " + source_file + " " + dest_folder)

You can use this function to launch other programs, for example, or perform such tasks as gathering all the material texture and displacement image files in your scene into one folder.

The DOSCommand() function returns an integer which is the status result returned by the executed system command.

ShellLaunch() emulates a user double-clicking on a specified file in Windows. It has the form:

ShellLaunch <filename_string> <parameters_string>

Whatever you send to ShellLaunch will be run by the Windows shell automatically, ie:

ShellLaunch "E:\\tests\\lookup.html" ""

would launch Netscape/Ie4 with lookup.html.

If a file-name extension is not specified in <filename_string>, Windows will search the specified directory for executable files. If no directory is specified, Windows will search the paths in the Path environment variable for the executable file. For example:

shellLaunch "e:/program files/ucalc/ucalc" ""

will execute the ucalc.exe file in the specified directory.

The <parameters_string> is passed to the launched application as command line parameters. For example:

shellLaunch "e:/t.avi" "/play /loop"

Will launch the application associated with .avi files, and pass /play and /loop as command line parameters.


Exiting and Resetting 3ds max

The quitMAX() function lets you exit 3ds max under script control. This function is typically used in batch processing or render scripts. The function has the form:

quitMAX [ #noPrompt ]

If the #noPrompt optional argument is not specified and there are unsaved changes in the scene, 3ds max will prompt with its standard save changes dialog.

Additionally, you can control the scene save and undo states in 3ds max with the following functions:

setSaveRequired <boolean>

lets you set the 3ds max system "dirty" flag. If this flag is set or there are entries in the Undo buffer, the user is asked if they want to save the scene file on a File > New or File > Reset.

getSaveRequired()

returns true if the 3ds max system "dirty" flag is set to true or if the Undo buffer is not empty. If the Undo buffer if not empty, this function will still return true, even if you just called setSaveRequired false.

clearUndoBuffer()

empties the Undo buffer, both providing a way to reset the undo state and another way to control the save-changes requester.

Normally, if there are entries in the Undo buffer when the scene is closed, 3ds max will prompt with a save-changes requester. In some cases, where you are controlling undo in MAXScript, you may want to force the need for a save-changes prompt.

The resetMAXFile() function lets you reset 3ds max under script control. This function is typically used in batch processing or render scripts. The function has the form:

resetMaxFile() [ #noPrompt ]

If the #noPrompt optional argument is not specified and there are unsaved changes in the scene, 3ds max will prompt with its standard save changes dialog.


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)

  • 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 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 Setting Up MAXScript OLE Automation for details.

OLE Client

With the MAXScript OLE Automation Client system, you can use MAXScript to create OLE Automation (now called Active-X) objects within 3ds max and control the associated OLE Automation Servers servers with MAXScript, such as making an Excel spreadsheet and inserting 3ds max object information directly into cells there.

The function createOLEObject() is used for establishing a connection to OLE Auto Servers. The return value of createOLEObject() is an instance of the OLEObject class. For example,

xl = createOLEObject "Excel.Sheet"

opens a connection to Excel and creates a sheet object and puts it in the variable xl. The single argument to this function is an OLE progID string. You can then access properties and call methods on the new OLE object. For example,

xl.application.name

will return

"Microsoft Excel"

xl.application.visible = true

will make Excel visible on the desktop. You get properties on OLE objects with the dot '.' notation, just as you do in MAXScript. You also refer to OLE object methods as properties of the OLE object. For example, the Sheet has a method 'cells' which takes a cell coordinate and returns a Cell OLE object.

xlc = xl.application.cells 1 1

puts the top-left-hand cell into xlc. Set its value like this:

xlc.value = 123.45

The server application that was attached with createOLEObject() is released and terminated when the created MAXScript OLE object is eventually garbage-collected. You can explicitly disconnect from an OLE server application with the releaseOLEObject() function. The form is:

releaseOLEObject <ole_object>

The OLE object becomes disabled once releaseOLEObject() has been called on it and further attempts to use it results in a descriptive error message.

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

3ds max Specific Errors

Running the OLE Demo


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


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 Setting Up MAXScript OLE Automation, 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).


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

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

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.

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.

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


MAXScript Grammar

The following is the complete MAXScript grammar in EBNF form. It differs slightly in factoring from the syntax forms given in the online reference, so that all precedence is explicit in the rules.

These rules, or syntax definitions, follow the standard EBNF notation (Extended Backus-Naur Form). The rules typically contain a number of characters with special meanings. For example, brackets enclose optional items, such as the minus sign in front of the number. Braces enclose items you can use repeatedly, and bars separate multiple items from which you can choose one. Sometimes, rules are given names so they can be referred to in the documentation or as parts of other rules. The special characters in the rules have the following meaning:

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

(...|...|...) -- choose one of the items separated by the bars

{...} -- you can specify the braced item ZERO or more times

{...}+ -- you can specify the braced item ONE or more times

::= -- define a name for a syntax rule

<rule> -- you can insert what is defined by the named rule

bold_characters -- characters or token as written

An example of an EBNF form is:

[-]{<digit>}[.{<digit>}][(e | E)[+ | -]{<digit>}+]

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

<program> ::= { <expr> }+

<expr> ::= <simple_expr>

<variable_decls>

<assignment>

<if_expr>

<while_loop>

<do_loop>

<for_loop>

<loop_exit>

<case_expr>

<struct_def>

<try_expr>

<variable_decls>

<function_def>

<function_return>

<context_expr>

<max_command>

<utility_def>

<rollout_def>

<tool_def>

<rcmenu_def>

<macroscript_def>

<plugin_def>

<variable_decls> ::= ( local | global ) <decl> { , <decl> }

persistent global <decl> { , <decl> }

<decl> ::= <var_name> [ = <expr> ] -- name and optional

-- initial value

<var_name> ::= { <alphanumeric> | _ }

'{ <any_char_except_quote> }'

<assignment> ::= <destination> = <expr>

<destination> += <expr>

<destination> -= <expr>

<destination> *= <expr>

<destination> /= <expr>

<destination> ::= <var_name>

<property>

<index>

<if_expr> ::= if <expr> then <expr> [ else <expr> ]

if <expr> do <expr>

<while_loop> ::= while <expr> do <expr>

<do_loop> ::= do <expr> while <expr>

<for_loop> ::= for <name> ( in | = ) <source> (do | collect) <expr>

<source> ::= <expr> to <expr> [ by <expr> ] [ where <expr> ]

<expr> [ where <expr> ]

<loop-exit> ::= exit [ with <expr> ]

<loop-continue> ::= continue

<case_expr> ::= case [ <expr> ] of ( { <case_item> } )

<case_item> ::= <factor> : <expr>

default : <expr>

<struct_def> ::= struct (<member> { , <member> } )

<member> ::= <name> [ = <expr> ] -- name and optional initial value

<function_def>

<try_expr> ::= try <expr> catch <expr>

<function_def> ::= [ mapped ] (function | fn) <var_name> { <arg> } = <expr>

<arg> ::= <var_name>

<var_name>: [ <operand> ]

<function_return> ::= return <expr>

<context_expr> ::= <context> { , <context> } <expr>

<context> ::= [with] animate <logical_expr>

at level <operand>

at time <operand>

in <operand>

[in] coordsys ( local | world | parent | <operand> )

about ( pivot | selection | coordsys | <operand> )

[ with ] undo <logical_expr>

<set_context> ::= set <context>

<utility_def> ::= utility <var_name> <string> { <var_name>:<operand> } \

( { <utility_clause> }+ )

<utility_clause> ::= <rollout>

<rollout_clause>

<rollout_def> ::= rollout <var_name> <string> { <var_name>:<operand> } \

( { <rollout_clause> }+ )

<rollout_clause> ::= local <decl> { , <decl> }

<function_def>

<struct_def>

<mousetool>

<item_group>

<rollout_item>

<rollout_handler>

<item_group> ::= group <string> ( { <rollout_item> } )

<rollout_handler> ::= on <var_name> <var_name> { <var_name> } do <expr>

<rollout_item> ::= <item_type> <var_name> [ <string> ] { <var_name>:<operand> }

<item_type> ::= label

button

edittext

combobox

dropdownList

listbox

spinner

slider

pickbutton

radiobuttons

checkbox

checkbutton

colorPicker

mapbutton

materialbutton

progressbar

timer

bitmap

<rcmenu_def> ::= rcmenu <var_name> ( { <rcmenu_clause> }+ )

<rcmenu_clause> ::= local <decl> { , <decl> }

<function_def>

<struct_def>

<rcmenu_item>

<rcmenu_handler>

<rcmenu_handler> ::= on <var_name> <var_name> do <expr>

<rcmenu_item> ::= <rcmenu_item_type> <var_name> <string> { <var_name>:<operand> }

<rcmenu_item_type>::= menuitem

separator

submenu

<macroscript_def> ::= macroscript <var_name> <string> { <var_name>:<operand> } \

( <expr_seq> )

<mousetool_def> ::= tool <var_name> { <var_name>:<operand> } ( { <tool_clause> }+ )

<tool_clause> ::= local <decl> { , <decl> }

<function_def>

<struct_def>

<tool_handler>

<tool_handler> ::= on <var_name> <var_name> { <var_name> } do <expr>

<plugin_def> ::= plugin <var_name> <var_name> { <var_name>:<operand> } \

( { <plugin_clause> }+ )

<plugin_clause> ::= local <decl> { , <decl> }

<function_def>

<struct_def>

<parameters>

<mousetool_def>

<rollout_def>

<plugin_handler>

<parameters> ::= parameters <var_name> { <var_name>:<operand> } ( { <param_clause> }+ )

<param_clause> ::= { <param_defs> }+

{ <param_handler> }

<param_defs> ::= <var_name> { <var_name>:<operand> }

<param_handler> ::= on <var_name> <var_name> { <var_name> } do <expr>

<plugin_handler> ::= on <var_name> do <expr>

<simple_expr> ::= <operand>

<math_expr>

<compare_expr>

<logical_expr>

<function_call>

<expr_seq>

<math_expr> ::= <math_operand> + <math_operand> -- standard arithmetic addition

<math_operand> - <math_operand> -- standard arithmetic subtraction

<math_operand> * <math_operand> -- standard arithmetic multiplication

<math_operand> / <math_operand> -- standard arithmetic division

<math_operand> ^ <math_operand> -- exponential, raise to the power

<math_operand> as <class> -- conversion between types

<math_operand> ::= <operand>

<function_call>

<math_expr>

<logical_expr> ::= <logical_operand> or <logical_operand>

<logical_operand> and <logical_operand>

not <logical_operand>

<logical_operand> ::= <operand>

<compare_expr>

<function_call>

<logical_expr>

<compare_expr> ::= <compare_operand> == <compare_operand> -- equal

<compare_operand> != <compare_operand> -- not equal

<compare_operand> > <compare_operand> -- greater than

<compare_operand> < <compare_operand> -- less than

<compare_operand> >= <compare_operand> -- greater than or equal

<compare_operand> <= <compare_operand> -- less than or equal

<compare_operand> ::= <math_expr>

<operand>

<function_call>

<function_call> ::= <operand> ()

<operand> { <parameter> } -- up to an end of line or

-- lower precedence token

<parameter> ::= <operand>

<name>: <operand>

<operand> ::= <factor>

<property>

<index>

<property> ::= <operand> . <var_name> -- properties and indexes

-- left associate

<index> ::= <operand> [ <expr> ]

<factor> ::= <number>

<string>

<path_name>

<var_name>

#<var_name>

<array>

<bitarray>

<point3>

<point2>

true

false

on

off

ok

undefined

unsupplied

- <expr> -- unary minus

<expr_seq>

? -- last Listener result

<expr_seq> ::= ( <expr> { (; | <eol>) <expr> } )

<number> ::= [-]{<digit>}[.{<digit>}[(e | E)[+ | -]{<digit>}+] -- decimal number

0x{<hex_digit>}+ -- hexadecimal number

<string> ::= "{ <any_char_except_quote> | \" | \n | \r | \t | \* | \? | \\ | \% | \x{<hex_digit>}+ }"

<time> ::= [-]{<decimal_number>[m | s | f | t]}+ -- minutes/sec/frames/ticks

[-]{<digit>}:{<digit>}[.{<digit>}] -- SMPTE mins:secs.frame

[-]<decimal_number>n -- active segment normalized time

<box2> ::= [ <expr>, <expr>, <expr>, <expr> ]

<point3> ::= [ <expr>, <expr>, <expr> ]

<point2> ::= [ <expr>, <expr> ]

<array> ::= #()

#( <expr> { , <expr> } )

<bitarray> ::= #{}

#{ [<expr> | <expr>..<expr>] { , [<expr> | <expr>..<expr>] } }

<path_name> ::= $<path> | $

<path> ::= [ <objectset> ] [ / ] [ <levels> ] <level_name>

<levels> ::= <level> { / <level> }

<level> ::= <level_name>

...

<level_name> ::= { <alphanumeric> | _ | * | ? | \ }

'{ <any_char_except_single_quote> | \* | \? | \\ }'


MAXScript Class Hierarchy

The following is the complete MAXScript class hierarchy. Each class typically inherits the properties, operators, and methods of its parent class.

Value

AngleAxis

Array

ArrayParameter

AtmosphericClass

BigMatrix

BigMatrixRowArray

BipedExportInterface

BitArray

Bitmap

BitmapControl

BooleanClass

Box2

ButtonControl

CTBitMap

CTMotionTracker

ChangeHandler

CharStream

CheckBoxControl

CheckButtonControl

Class

Color

ColorPickerControl

ComboBoxControl

Control

EdgeSelection

EditTextControl

EffectClass

EmptyClass

EulerAngles

FaceSelection

FileStream

Float

GeomObject

GroupEndControl

GroupStartControl

HashTable

Integer

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

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

SliderControl

SpinnerControl

StandardMaterialClass

String

StringStream

StructDef

SubAnim

Time

Timer

TriMesh

UndefinedClass

UnsuppliedClass

UserGeneric

VertexSelection

WindowStream

XRefScene

MAXWrapper

atmospheric

Fire_Effect

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


DWG Link File Access for VIZ

MAXScript for 3D Studio VIZ includes a function for DWG link file access. Its form is:

linkFile <filename_string> [#noPrompt]

This method attaches and links the named .DWG file and returns a value of true if the file was attached and linked, false otherwise. This method is equivalent to Menu bar > Insert > Linked DWG... in 3DS VIZ. The optional #noPrompt argument provides control over the display of the DWG Link Options dialog. This method is available only to VIZ users.

See also

External File Methods

File Name Parsing

Standard Open and Save File Dialogs


Foliage : GeometryClass

Foliage - GeometryClass

Constructor

foliage ...

Note: This class is not available in 3ds max.

Properties

<Foliage>.height Float default: 1.0

<Foliage>.Density Float default: 1.0

<Foliage>.Pruning Float default: 0.0

<Foliage>.seed Integer default: varies per instance

<Foliage>.GenUV Boolean default: true

<Foliage>.ShowLeaves Boolean default: true

<Foliage>.ShowTrunk Boolean default: true

<Foliage>.ShowFruit Boolean default: true

<Foliage>.ShowBranches Boolean default: true

<Foliage>.ShowFlowers Boolean default: true

<Foliage>.ShowRoots Boolean default: true

<Foliage>.CanopyMode Integer default: 0

CanopyMode = 0 – When Not Selected; 1 – Always; 2 - Never

<Foliage>.LevelOfDetail Integer default: 2

LevelOfDetail = 0 – Low; 1 – Medium; 2 - High

Notes

While you can create a Foliage object in MAXScript, you cannot specify the plant type, so the Generic Tree plant type is always created.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Free_Point : Light and Target_Point : Light

The following properties apply to both the Free_Point and Target_Point light types present in 3D Studio VIZ.

Constructor

Free_point ...

Target_point ...

Note: Point light objects are not available in 3ds max.

Properties

<point_light>.on Boolean default: true -- alias: Light_On

<point_light>.type String default: varies -- alias: Light_Type

type = "point_light" = free point light; "Target_Point" = target point light

<point_light>.distribution Integer default: 0 -- alias: Distirbution_Type

distribution = 0 - Isotropic; 1 - SpotLight; 2 - Web

<point_light>.castShadows Boolean default: true -- alias: Cast_Shadows

<point_light>.excludeList Array default: #() -- alias: Exclude_List

<point_light>.includeList Array default: #() -- alias: Include_List

<point_light>.useKelvin Boolean default: false -- alias: Use_Kelvin

<point_light>.kelvin Float default: 3600.0

<point_light>.rgb Color default: (color 255 255 255) -- alias: Light_Color, color

<point_light>.rgbFilter Color default: (color 255 255 255) -- alias: Filter_Color

<point_light>.multiplier Float default: 1500.0 -- alias: Intensity

<point_light>.showCone Boolean default: false -- alias: Cone_Display

<point_light>.hotSpot Float default: 30.0 -- alias: Beam_Angle

<point_light>.fallSize Float default: 60.0 -- alias: Field_Angle

<point_light>.webFile String default: "" -- alias: Web_Filename

<point_light>.xRotation Float default: 0.0 -- alias: X_Rotation

<point_light>.yRotation Float default: 0.0 -- alias: Y_Rotation

<point_light>.zRotation Float default: 0.0 -- alias: Z_Rotation

<point_light>.contrast Float default: 0.0 -- alias: Light_Contrast

<point_light>.softenDiffuseEdge Float default: 0.0 -- alias: Diffuse_Soften

<point_light>.affectDiffuse Boolean default: true -- alias: Affect_Diffuse

<point_light>.affectSpecular Boolean default: true -- alias: Affect_Diffuse

<point_light>.ambientOnly Boolean default: false -- alias: Ambient_Only

<point_light>.projector Boolean default: false

<point_light>.projectorMap TextureMap default: undefined -- alias: Projector_Map

<point_light>.targetDistance Float default: 240.0 -- alias: Target_Distance

<point_light>.raytracedShadows Boolean default: false

raytracedShadows = false - use Shadow Map; true - use Ray Traced Shadows

<point_light>.shadowGeneratorByName String default: "Shadow Map" -- alias: Shadow_Generator_by_Name

Enter "Shadow Map" for shadow maps; "Ray Traced Shadows" for ray traced shadows

<point_light>.shadowGenerator Undefined default: undefined -- alias: Shadow_Generator

<point_light>.useGlobalShadowSettings Boolean default: false -- alias: Use_Global_Params

<point_light>.shadowColor Color default: (color 0 0 0) -- alias: Shadow_Color

<point_light>.shadowMultiplier Float default: 1.0 -- alias: Shadow_Density

<point_light>.shadowColorMapEnable Boolean default: false -- alias: Use_Shadow_Color_Map

<point_light>.shadowProjectorMap TextureMap default: undefined -- alias: Shadow_Projector_Map

<point_light>.lightAffectsShadow Boolean default: false -- alias: Light_Affects_Shadow

<point_light>.atmosShadows Boolean default: false -- alias: Atmospheric_Shadows_On

<point_light>.atmosOpacity Float default: 100.0 -- alias: Atmospheric_Opacity

<point_light>.atmosColorAmt Float default: 100.0 -- alias: Atmospheric_Color_Amount

If Shadow Maps are being used (raytracedShadows = false), the shadow properties are:

<point_light>.mapbias Float default: 1.0 -- alias: Map_Bias

<point_light>.mapsize Integer default: 512 -- alias: Map_Size

<point_light>.samplerange Float default: 4.0 -- alias: Map_Range

<point_light>.absoluteMapBias Boolean default: false -- alias: Absolute_Bias

If Ray Traced Shadows are being used (raytracedShadows = true), the shadow properties are:

<point_light>.raytraceBias Float default: 0.2 -- alias: Bias

<point_light>.maxDepth Integer default: 7

<point_light>.radiance_map UndefinedClass default: undefined

<point_light>.shadowGenerator UndefinedClass default: undefined -- max object; alias: Shadow_Generator

<point_light>.radianceMap UndefinedClass default: undefined -- max object; alias: Radiance_Map

See also

Light Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Geometry - AEC Extended Objects

The following list displays the AEC Extended objects:

Terrain

Foliage

Railing


Geometry - Stairs

The following list displays the Stair objects:

L_Type_Stair

Spiral_Stair

Straight_Stair

U_Type_Stair

Note: The Stair objects are not available in 3ds max.


Host_Composite : GeometryClass

Host_Composite - GeometryClass

Constructor

Host_Composite objects are in some cases automatically created when using Modeling Context. Host_Composite objects are not creatable in MAXScript.

Note: This class is not available in 3ds max.

Properties

There are no properties associated with this class.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


L_Type_Stair : GeometryClass

L_Type_Stair - GeometryClass

Constructor

L_Type_Stair ...

Note: This class is not available in 3ds max.

Properties

<L_Type_Stair>.StepType Integer default: 0

StepType = 0 - Open; 1 - Closed; 2 - Box

<L_Type_Stair>.GenerateStringers Integer default: 0

GenerateStringers = 0 - off; 1 - on

<L_Type_Stair>.GenerateCarriage Integer default: 1

GenerateCarriage = 0 - off; 1 - on

<L_Type_Stair>.GenerateInsideRailing Integer default: 0

GenerateInsideRailing = 0 - off; 1 - on

<L_Type_Stair>.GenerateOutsideRailing Integer default: 0

GenerateOutsideRailing = 0 - off; 1 - on

<L_Type_Stair>.GenerateInsidePath Integer default: 0

GenerateInsidePath = 0 - off; 1 - on

<L_Type_Stair>.GenerateOutsidePath Integer default: 0

GenerateOutsidePath = 0 - off; 1 - on

<L_Type_Stair>.length Float default: 0.0

<L_Type_Stair>.length2 Float default: 0.0

<L_Type_Stair>.Stepwidth Float default: 39.0

<L_Type_Stair>.angle Float default: 45.0

<L_Type_Stair>.UpperOffset Float default: 0.0

<L_Type_Stair>.StepHeightType Integer default: 0

StepHeightType = 0 - Overall; 1 - Riser Ht. 2 - Riser Ct.

<L_Type_Stair>.TotalHeight Float default: 72.0

<L_Type_Stair>.StepHeight Float default: 6.0

<L_Type_Stair>.StepCount Integer default: 12

<L_Type_Stair>.StepThickness Float default: 2.0

<L_Type_Stair>.StepDepth_X Integer default: 0

StepDepth_X = 0 - off; 1 - on

<L_Type_Stair>.StepDepth Float default: 12.0

<L_Type_Stair>.GenerateMapping Integer default: 0

GenerateMapping = 0 - off; 1 - on

<L_Type_Stair>.StringerDepth Float default: 6.0

<L_Type_Stair>.StringerWidth Float default: 1.0

<L_Type_Stair>.StringerOffset Float default: 1.0

<L_Type_Stair>.StringerSpringFloor Integer default: 1

StringerSpringFloor = 0 - off; 1 - on

<L_Type_Stair>.CarriageHeight Float default: 8.0

<L_Type_Stair>.CarriageWidth Float default: 3.0

<L_Type_Stair>.CarriageCount_X Integer default: 1

CarriageCount_X = 0 - off; 1 - on

<L_Type_Stair>.CarriageCount Float default: 0.0

<L_Type_Stair>.CarriageSpace_X Integer default: 0

CarriageSpace_X = 0 - off; 1 - on

<L_Type_Stair>.CarriageSpace Float default: 10.0

<L_Type_Stair>.CarriageIntOffs_X Integer default: 1

CarriageIntOffs_X = 0 - off; 1 - on

<L_Type_Stair>.CarriageIntOffs Float default: 3.0

<L_Type_Stair>.CarriageExtOffs_X Integer default: 1

CarriageExtOffs_X = 0 - off; 1 - on

<L_Type_Stair>.CarriageExtOffs Float default: 3.0

<L_Type_Stair>.CarriageLockOffs Integer default: 18

CarriageLockOffs = 18 - Both Start and End Offset locked; 15 - Only Start Offset locked; 12 - Only End Offset locked; 1 - Neither locked

<L_Type_Stair>.CarriageSpringFloor Integer default: 1

CarriageSpringFloor = 0 - off; 1 - on

<L_Type_Stair>.RailingHeight Float default: 42.0

<L_Type_Stair>.RailingOffs Float default: 2.0

<L_Type_Stair>.RailingSegments Integer default: 3

<L_Type_Stair>.RailingRadius Float default: 1.0

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Link_Transform : Matrix3Controller

Constructor

Link_Transform controllers are created when a DWG file is linked by VIZ. For each of the VIZ objects created by the DWG link, a Link_Transform controller is assigned to the transform track of the object, and the transform controller from the DWG file is applied as a child of the Link_Transform controller. Link_Transform controllers are not creatable in MAXScript.

Note: This class is not available in 3ds max.

Properties

<link_transform>.transform Matrix3Controller

Contains the transform controller below the link_transform controller

See also

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


LinkComposite : GeometryClass

LinkComposite - GeometryClass

Constructor

LinkComposite objects are created when a DWG file is linked by VIZ. Each of the VIZ objects created by the DWG link is created as an instance of this class. LinkComposite objects are not creatable in MAXScript.

Note: This class is not available in 3ds max.

Properties

There are no properties associated with this class.

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


LinkOriginPtHelper : Helper

LinkOriginPtHelper - Helper

Constructor

LinkOriginPtHelper objects are created when a DWG file is linked by VIZ. A LinkOriginPtHelper object is created, and then each of the VIZ objects created by the DWG link is created as a child object of the LinkOriginPtHelper. LinkOriginPtHelper objects are not creatable in MAXScript.

Note: This class is not available in 3ds max.

Properties

There are no properties associated with this class.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Railing : GeometryClass

Railing - GeometryClass

Constructor

railing ...

Note: This class is not available in 3ds max.

Properties

<Railing>.Respect_Path_Corners_in_rails Boolean default: false

<Railing>.Number_of_segments_between_each_pair_of_Posts Integer default: 1

<Railing>.Railing_Length Float default: 0.0

<Railing>.Top_Rail_Profile Integer default: 2

Top_Rail_Profile = 0 - (none); 1 – Round; 2 - Square

<Railing>.Top_Rail_Depth Float default: 4.0

<Railing>.Top_Rail_Width Float default: 3.0

<Railing>.Top_surface_of_Top_Rail_Height Float default: 42.0

<Railing>.Lower_Rail_Profile Integer default: 2

Lower_Rail_Profile = 0 - (none); 1 – Round; 2 - Square

<Railing>.Lower_Rail_Depth Float default: 2.0

<Railing>.Lower_Rail_Width Float default: 1.0

<Railing>.Number_of_Lower_Rails Integer default: 1

<Railing>.Lower_Rail_Spacing Float default: 0.0

<Railing>.Lowest_Rail_Height Float default: 0.0

<Railing>.Texture_Mapped Boolean default: false

<Railing>.Post_Profile Integer default: 2

Post_Profile = 0 - (none); 1 – Round; 2 - Square

<Railing>.Post_Depth Float default: 2.0

<Railing>.Post_Width Float default: 2.0

<Railing>.Post_Extension_beyond_bottom_of_Top_Rail Float

default: 0.0

<Railing>.Number_of_Posts Integer default: 2

<Railing>.Post_Spacing Float default: 0.0

<Railing>.First_Post_Offset Float default: 1.0

<Railing>.Posts_oriented_with_curved_Railing Boolean default: true

<Railing>.Fencing_Type Integer default: 1

Fencing_Type = 0 – (none); 1 – Pickets; 2 – Solid Fill

<Railing>.Picket_Profile Integer default: 2

Picket_Profile = 0 – Round; 1 - Square

<Railing>.Picket_Depth Float

default: 1.0

<Railing>.Picket_Width Float default: 1.0

<Railing>.Picket_Extension_beyond_bottom_of_Top_Rail Float default: 0.0

<Railing>.Picket_Bottom_Offset Float default: 0.0

<Railing>.Number_of_Pickets_between_each_pair_of_Posts Integer default: 2

<Railing>.Picket_Spacing Float default: 0.0

<Railing>.First_Picket_Offset Float default: 0.0

<Railing>.Pickets_oriented_with_curved_Railing Boolean default: true

<Railing>.Fill_Thickness Float default: 0.25

<Railing>.Fill_Top_Offset Float default: 0.0

<Railing>.Fill_Bottom_Offset Float default: 0.0

<Railing>.Fill_Left_Offset Float default: 0.0

<Railing>.Fill_Right_Offset Float default: 0.0

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Spiral_Stair : GeometryClass

Spiral_Stair - GeometryClass

Constructor

Spiral_Stair ...

Note: This class is not available in 3ds max.

Properties

<Spiral_Stair>.StepType Integer default: 0

StepType = 0 - Open; 1 - Closed; 2 - Box

<Spiral_Stair>.GenerateStringers Integer default: 0

GenerateStringers = 0 - off; 1 - on

<Spiral_Stair>.GenerateCarriage Integer default: 1

GenerateCarriage = 0 - off; 1 - on

<Spiral_Stair>.GenerateCenterPole Integer default: 0

GenerateCenterPole = 0 - off; 1 - on

<Spiral_Stair>.GenerateInsideRailing Integer default: 0

GenerateInsideRailing = 0 - off; 1 - on

<Spiral_Stair>.GenerateOutsideRailing Integer default: 0

GenerateOutsideRailing = 0 - off; 1 - on

<Spiral_Stair>.GenerateInsidePath Integer default: 0

GenerateInsidePath = 0 - off; 1 - on

<Spiral_Stair>.GenerateOutsidePath Integer default: 0

GenerateOutsidePath = 0 - off; 1 - on

<Spiral_Stair>.direction Integer default: 0

direction = 0 - Counterclockwise; 1 - Clockwise

<Spiral_Stair>.radius Float default: 40.0

<Spiral_Stair>.Revolutions Float default: 0.75

<Spiral_Stair>.Stepwidth Float default: 39.0

<Spiral_Stair>.StepHeightType Integer default: 0

StepHeightType = 0 - Overall; 1 - Riser Ht. 2 - Riser Ct.

<Spiral_Stair>.TotalHeight Float default: 72.0

<Spiral_Stair>.StepHeight Float default: 6.0

<Spiral_Stair>.StepCount Integer default: 12

<Spiral_Stair>.StepThickness Float default: 2.0

<Spiral_Stair>.StepDepth_X Integer default: 0

StepDepth_X = 0 - off; 1 - on

<Spiral_Stair>.StepDepth Float default: 12.0

<Spiral_Stair>.StepSegments_X Integer default: 0

StepSegments_X = 0 - off; 1 - on

<Spiral_Stair>.StepSegments Integer default: 1

<Spiral_Stair>.GenerateMapping Integer default: 0

GenerateMapping = 0 - off; 1 - on

<Spiral_Stair>.StringerDepth Float default: 6.0

<Spiral_Stair>.StringerWidth Float default: 1.0

<Spiral_Stair>.StringerOffset Float default: 1.0

<Spiral_Stair>.StringerSpringFloor Integer default: 1

StringerSpringFloor = 0 - off; 1 - on

<Spiral_Stair>.CarriageHeight Float default: 8.0

<Spiral_Stair>.CarriageWidth Float default: 3.0

<Spiral_Stair>.CarriageCount_X Integer default: 1

CarriageCount_X = 0 - off; 1 - on

<Spiral_Stair>.CarriageCount Integer default: 1

<Spiral_Stair>.CarriageSpace_X Integer default: 0

CarriageSpace_X = 0 - off; 1 - on

<Spiral_Stair>.CarriageSpace Float default: 10.0

<Spiral_Stair>.CarriageIntOffs_X Integer default: 1

CarriageIntOffs_X = 0 - off; 1 - on

<Spiral_Stair>.CarriageIntOffs Float default: 3.0

<Spiral_Stair>.CarriageExtOffs_X Integer default: 1

CarriageExtOffs_X = 0 - off; 1 - on

<Spiral_Stair>.CarriageExtOffs Float default: 3.0

<Spiral_Stair>.CarriageLockOffs Integer default: 18

CarriageLockOffs = 18 - Both Start and End Offset locked; 15 - Only Start Offset locked; 12 - Only End Offset locked; 1 - Neither locked

<Spiral_Stair>.CarriageSpringFloor Integer default: 1

CarriageSpringFloor = 0 - off; 1 - on

<Spiral_Stair>.CenterPoleRadius Float default: 10.0

<Spiral_Stair>.CenterPoleSegments Integer default: 16

<Spiral_Stair>.CenterPoleHeight_X Integer default: 0

CenterPoleHeight_X = 0 - off; 1 - on

<Spiral_Stair>.CenterPoleHeight Float default: 240.0

<Spiral_Stair>.RailingHeight Float default: 42.0

<Spiral_Stair>.RailingOffs Float default: 2.0

<Spiral_Stair>.RailingSegments Integer default: 3

<Spiral_Stair>.RailingRadius Float default: 1.0

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Straight_Stair : GeometryClass

Straight_Stair - GeometryClass

Constructor

Straight_Stair ...

Note: This class is not available in 3ds max.

Properties

<Straight_Stair>.StepType Integer default: 0

StepType = 0 - Open; 1 - Closed; 2 - Box

<Straight_Stair>.GenerateStringers Integer default: 0

GenerateStringers = 0 - off; 1 - on

<Straight_Stair>.GenerateCarriage Integer default: 1

GenerateCarriage = 0 - off; 1 - on

<Straight_Stair>.GenerateInsideRailing Integer default: 0

GenerateInsideRailing = 0 - off; 1 - on

<Straight_Stair>.GenerateOutsideRailing Integer default: 0

GenerateOutsideRailing = 0 - off; 1 - on

<Straight_Stair>.GenerateInsidePath Integer default: 0

GenerateInsidePath = 0 - off; 1 - on

<Straight_Stair>.GenerateOutsidePath Integer default: 0

GenerateOutsidePath = 0 - off; 1 - on

<Straight_Stair>.length Float default: 0.0

<Straight_Stair>.Stepwidth Float default: 39.0

<Straight_Stair>.StepHeightType Integer default: 0

StepHeightType = 0 - Overall; 1 - Riser Ht. 2 - Riser Ct.

<Straight_Stair>.TotalHeight Float default: 72.0

<Straight_Stair>.StepHeight Float default: 6.0

<Straight_Stair>.StepCount Integer default: 12

<Straight_Stair>.StepThickness Float default: 2.0

<Straight_Stair>.StepDepth_X Integer default: 0

StepDepth_X = 0 - off; 1 - on

<Straight_Stair>.StepDepth Float default: 12.0

<Straight_Stair>.GenerateMapping Integer default: 0

GenerateMapping = 0 - off; 1 - on

<Straight_Stair>.StringerDepth Float default: 6.0

<Straight_Stair>.StringerWidth Float default: 1.0

<Straight_Stair>.StringerOffset Float default: 1.0

<Straight_Stair>.StringerSpringFloor Integer default: 1

StringerSpringFloor = 0 - off; 1 - on

<Straight_Stair>.CarriageHeight Float default: 8.0

<Straight_Stair>.CarriageWidth Float default: 3.0

<Straight_Stair>.CarriageCount_X Integer default: 1

CarriageCount_X = 0 - off; 1 - on

<Straight_Stair>.CarriageCount Float default: 0.0

<Straight_Stair>.CarriageSpace_X Integer default: 0

CarriageSpace_X = 0 - off; 1 - on

<Straight_Stair>.CarriageSpace Float default: 10.0

<Straight_Stair>.CarriageIntOffs_X Integer default: 1

CarriageIntOffs_X = 0 - off; 1 - on

<Straight_Stair>.CarriageIntOffs Float default: 3.0

<Straight_Stair>.CarriageExtOffs_X Integer default: 1

CarriageExtOffs_X = 0 - off; 1 - on

<Straight_Stair>.CarriageExtOffs Float default: 3.0

<Straight_Stair>.CarriageLockOffs Integer default: 18

CarriageLockOffs = 18 - Both Start and End Offset locked; 15 - Only Start Offset locked; 12 - Only End Offset locked; 1 - Neither locked

<Straight_Stair>.CarriageSpringFloor Integer default: 1

CarriageSpringFloor = 0 - off; 1 - on

<Straight_Stair>.RailingHeight Float default: 42.0

<Straight_Stair>.RailingOffs Float default: 2.0

<Straight_Stair>.RailingSegments Integer default: 3

<Straight_Stair>.RailingRadius Float default: 1.0

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Substitute : Modifier

Constructor

substitute ...

substituteMod ...

Note: This class is not available in 3ds max.

Properties

<Substitute>.DisplayInViewport Boolean default: true

<Substitute>.DisplayInRender Boolean default: true

<Substitute>.ObjectName String default: "" -- alias: SceneNodeName

<Substitute>.ObjectReference Node default: undefined -- alias: SelectFrom

<Substitute>.MoveCopyInstance Integer default: 2

<Substitute>.SubstituteType String default: "" -- alias: Substitute_Type

<Substitute>.RetainPosition Boolean default: false

See also

Modifier Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


U_Type_Stair : GeometryClass

U_Type_Stair - GeometryClass

Constructor

U_Type_Stair ...

Note: This class is not available in 3ds max.

Properties

<U_Type_Stair>.StepType Integer default: 0

StepType = 0 - Open; 1 - Closed; 2 - Box

<U_Type_Stair>.GenerateStringers Integer default: 0

GenerateStringers = 0 - off; 1 - on

<U_Type_Stair>.GenerateCarriage Integer default: 1

GenerateCarriage = 0 - off; 1 - on

<U_Type_Stair>.GenerateInsideRailing Integer default: 0

GenerateInsideRailing = 0 - off; 1 - on

<U_Type_Stair>.GenerateOutsideRailing Integer default: 0

GenerateOutsideRailing = 0 - off; 1 - on

<U_Type_Stair>.GenerateInsidePath Integer default: 0

GenerateInsidePath = 0 - off; 1 - on

<U_Type_Stair>.GenerateOutsidePath Integer default: 0

GenerateOutsidePath = 0 - off; 1 - on

<U_Type_Stair>.direction Integer default: 0

direction = 0 - Left; 1 - Right

<U_Type_Stair>.length Float default: 0.0

<U_Type_Stair>.length2 Float default: 0.0

<U_Type_Stair>.Stepwidth Float default: 39.0

<U_Type_Stair>.UpperOffset Float default: 0.0

<U_Type_Stair>.StepHeightType Integer default: 0

StepHeightType = 0 - Overall; 1 - Riser Ht. 2 - Riser Ct.

<U_Type_Stair>.TotalHeight Float default: 72.0

<U_Type_Stair>.StepHeight Float default: 6.0

<U_Type_Stair>.StepCount Integer default: 12

<U_Type_Stair>.StepThickness Float default: 2.0

<U_Type_Stair>.StepDepth_X Integer default: 0

StepDepth_X = 0 - off; 1 - on

<U_Type_Stair>.StepDepth Float default: 12.0

<U_Type_Stair>.GenerateMapping Integer default: 0

GenerateMapping = 0 - off; 1 - on

<U_Type_Stair>.StringerDepth Float default: 6.0

<U_Type_Stair>.StringerWidth Float default: 1.0

<U_Type_Stair>.StringerOffset Float default: 1.0

<U_Type_Stair>.StringerSpringFloor Integer default: 1

StringerSpringFloor = 0 - off; 1 - on

<U_Type_Stair>.CarriageHeight Float default: 8.0

<U_Type_Stair>.CarriageWidth Float default: 3.0

<U_Type_Stair>.CarriageCount_X Integer default: 1

CarriageCount_X = 0 - off; 1 - on

<U_Type_Stair>.CarriageCount Float default: 0.0

<U_Type_Stair>.CarriageSpace_X Integer default: 0

CarriageSpace_X = 0 - off; 1 - on

<U_Type_Stair>.CarriageSpace Float default: 10.0

<U_Type_Stair>.CarriageIntOffs_X Integer default: 1

CarriageIntOffs_X = 0 - off; 1 - on

<U_Type_Stair>.CarriageIntOffs Float default: 3.0

<U_Type_Stair>.CarriageExtOffs_X Integer default: 1

CarriageExtOffs_X = 0 - off; 1 - on

<U_Type_Stair>.CarriageExtOffs Float default: 3.0

<U_Type_Stair>.CarriageLockOffs Integer default: 18

CarriageLockOffs = 18 - Both Start and End Offset locked; 15 - Only Start Offset locked; 12 - Only End Offset locked; 1 - Neither locked

<U_Type_Stair>.CarriageSpringFloor Integer default: 1

CarriageSpringFloor = 0 - off; 1 - on

<U_Type_Stair>.RailingHeight Float default: 42.0

<U_Type_Stair>.RailingOffs Float default: 2.0

<U_Type_Stair>.RailingSegments Integer default: 3

<U_Type_Stair>.RailingRadius Float default: 1.0

See also

GeometryClass Common Properties, Operators, and Methods

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


MAXScript Extensions in character studio 3

CS3Tools.cui Tutorial

Biped MAXScript Extensions

Crowd MAXScript Extensions


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

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 Macro Scripts and Defining Macro Scripts for additional details regarding Macro Scripts.

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 Creating Icon Bitmap Files for more information on creating and customizing icon bitmaps.

For access to Custom User Interface (CUI) files using MAXScript, see Custom User Interface Files. 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 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 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

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 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 Macro Scripts and Defining Macro Scripts 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.

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 to include the code in CS3Customkeys.ms. The included code redefines the global key_buffers already defined.

The file \3ds3.1\Scripts\Startup\CS3Customkeys.ms Tutorial_File_name_CS3Customkeys_ms contains the following functions:

fn Set_One_Key_FN

fn Set_Key_FN

fn CS3Save_Presets

fn CS3Show_key_FN

fn CS3Change_Key_FN

fn ControllerOf

fn RootOf

The functions Change_Key_FN, Save_Presets and Set_Key_FN will be reviewed in more detail below.

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

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 == 0 ) then

(

messagebox "No object selected.\nPlease select a Biped Object first.\n"

return local_key_buffer

)

if ($selection.count > 1) then

(

messagebox "There are multiple objects selected.\nPlease select a single Biped Object first."

return local_key_buffer

)

if ((classof $) != 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 == 2) then

(

my_controller = my_controller.vertical.controller

)

else if (my_controller.trackselection ==1) then

(

my_controller = my_controller.horizontal.controller

)

else if (my_controller.trackselection == 3) then

(

my_controller = my_controller.turning.controller

)

else

(

msgtext = "'" + $.name + "' skipped.\n"

messagebox msgtext

return local_key_buffer

)

)

if (my_root.transform.controller.figuremode == 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 == 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 == 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 my_controller slidertime

-- format "Key Index = %\n" my_index

if (my_index>0) then

(

my_key = biped.getKey my_controller my_index

-- format "key type is % \n" my_key.type

if (my_key.type == #body) then

(

local_key_buffer.ikblend = my_key.ikblend

local_key_buffer.ikspace = my_key.ikspace

local_key_buffer.ikAnkleTension = my_key.ikAnkleTension

)

if (my_key.type == #vertical) then

(

local_key_buffer.dynamicsblend = my_key.dynamicsblend

local_key_buffer.ballistictension = my_key.balistictension

)

if (my_key.type == #horizontal) then

(

local_key_buffer.balancefactor = my_key.balancefactor

)

local_key_buffer.easefrom = my_key.easeto

local_key_buffer.easeto = my_key.easefrom

local_key_buffer.tension = my_key.tension

local_key_buffer.continuity = my_key.continuity

local_key_buffer.bias = my_key.bias

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 + "startup\CS3CustomKeys-presets.ini"

outfile = createfile my_path

format "-- This file was created by the CS3 Custom Key Macro \"Save_Key_Presets\" to store user-customized presets for Biped custom key macro tools\n" to:outfile

format "-- These values can be editted by hand for existing fields\n\n" to:outfile

k = keya_buffer

format "Global keya_buffer = Biped_key type:% ikblend:% ikspace:% easefrom:% easeto:% tension:% continuity:% bias:%\n" k.type k.ikblend k.ikspace k.easefrom k.easeto k.tension k.continuity k.bias to:outfile

k = keyb_buffer

format "Global keyb_buffer = Biped_key type:% ikblend:% ikspace:% easefrom:% easeto:% tension:% continuity:% bias:%\n" k.type k.ikblend k.ikspace k.easefrom k.easeto k.tension k.continuity k.bias to:outfile

k = keyc_buffer

format "Global keyc_buffer = Biped_key type:% ikblend:% ikspace:% easefrom:% easeto:% tension:% continuity:% bias:%\n" k.type k.ikblend k.ikspace k.easefrom k.easeto k.tension k.continuity k.bias to:outfile

k = keyd_buffer

format "Global keyd_buffer = Biped_key type:% ikblend:% ikspace:% easefrom:% easeto:% tension:% continuity:% bias:%\n" k.type k.ikblend k.ikspace k.easefrom k.easeto k.tension k.continuity k.bias to:outfile

k = keye_buffer

format "Global keye_buffer = Biped_key type:% ikblend:% ikspace:% easefrom:% easeto:% tension:% continuity:% bias:%\n" k.type k.ikblend k.ikspace k.easefrom k.easeto k.tension k.continuity k.bias to:outfile

k = keyf_buffer

format "Global keyf_buffer = Biped_key type:% ikblend:% ikspace:% easefrom:% easeto:% tension:% continuity:% bias:%\n" k.type k.ikblend k.ikspace k.easefrom k.easeto k.tension k.continuity k.bias to:outfile

close 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

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.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.count == 1) and ((classof $) != 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.count do

(

if ((classof $selection[i]) != Biped_Object) then

(

msgtext = "The selected object '" + $selection[i].name + "' is not a Biped Object.\nObject Skipped.\n"

messagebox msgtext

continue

)

my_root = $selection[i].controller.rootnode

if (my_root.transform.controller.figuremode == 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 == 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 == 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 == 1) then

(

my_controller = my_controller.horizontal.controller

)

else if (my_controller.trackselection == 2) then

(

my_controller = my_controller.vertical.controller

)

else if (my_controller.trackselection == 3) then

(

my_controller = my_controller.turning.controller

)

else

(

msgtext = "'" + $selection[i].name + "' skipped.\n"

messagebox msgtext

continue

)

)

-- loop through all keys and call only if a key is selected

if (keyboardshiftpressed_atstart == true) then -- user wants to process all selected keys in this track

(

found_selected_keys = 0

for temp_index=1 to (numkeys my_controller) do

(

if (iskeyselected my_controller temp_index) then

(

set_one_key_FN my_controller temp_index local_key_buffer -- set this key to the local key buffer

found_selected_keys += 1

)

)

if (found_selected_keys == 0 ) then

(

msgtext = "Warning: No keys selected.\nNo changes made to " + $selection[i].name + "."

messagebox (msgtext)

)

else

(

msgtext = "Changed " + (found_selected_keys as string) + " keys in " + $selection[i].name + "."

messagebox (msgtext)

)

)

else -- (default) user wants to process just the current key

(

temp_index = getkeyindex my_controller slidertime

-- format "index of key at this frame (temp_index) is %\n" temp_index

if (temp_index == 0) then -- no key at this frame yet, let's create one...

(

biped.addNewKey my_controller slidertime #select

temp_index = getkeyindex my_controller slidertime

)

-- 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 the button, choose "Edit Button Appearance", modify the text in the "Tooltip:" text box and click OK.

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 Macro Scripts and Defining Macro Scripts for additional details.

See also

Biped MaxScript Extensions

Crowd MaxScript Extensions


Biped MAXScript Extensions

Biped Creation

Biped Display Preferences

Biped Load and Save

Biped Node Hierarchy

Biped Layers

Biped Footsteps and Footprints

FootSteps : Matrix3 Controller

Biped Footprints

Biped MultFprintParams Class

Biped Controllers

Biped Slave Controller

Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller

Biped Keys

BipedFSKey : MAXObject

BipedKey : MAXObject

Biped Motion Capture

Biped Motion Flow

MoFlow : MaxWrapper

MoFlowScript : MaxWrapper

MoFlowSnippet : MaxWrapper

MoFlowTranInfo : MaxWrapper

MoFlowTransition : MaxWrapper

Biped and Crowd Interaction

Biped Sample Scripts


Biped Load and Save

Biped Load and Save Methods

This topic covers the load and save methods for motion, figure, score, keys, motion capture, and talent files.

-- Motion File Access Methods

biped.LoadBipFile <biped_ctrl> <filename>

Load a biped motion file. Motion files include, footsteps, keyframe settings, the biped scale, and the active gravity value (GravAccel). IK Blend values for the keys and Object Space Object information are also loaded.

biped.SaveBipFile <biped_ctrl> <filename>

Save a biped motion file. A .bip file includes footsteps and keyframe data. Biped files store the complete movement and allow you to create libraries of motion. Create your own .bip library by animating the biped and saving a .bip file.

Notes

Load/Save a Biped (.BIP) file

-- Figure File Access Methods

biped.LoadFigFile <biped_ctrl> <filename>

Load a Figure file. Figure mode must be active to load a Figure file. Figure files allow you to apply the structure of one biped to another. Reload a Figure file if you accidentally lose your biped Figure mode pose; this pose is the biped fitted to a mesh.

biped.SaveFigFile <biped_ctrl> <filename>

Save the structure and position of a biped in Figure mode. After fitting the biped to a mesh in Figure mode, save a figure file. If the biped is accidentally moved in Figure mode, reload this file.

Notes

Load/Save a Figure (*.FIG) file

-- Score File Access Methods

biped.LoadScoreFile <biped_ctrl> <filename>

biped.SaveScoreFile <biped_ctrl> <filename>

Score files are Step files which save footsteps, but don't save body keyframes. They are an ASCII file format that enables developers to write programs that generate step files for biped motion. The online document stp.rtf, provided with character studio in the \cstudio\docs directory, describes the .stp format.

Notes

Load/Save a Step (*.STP) file

-- Motion Capture File Access Methods

biped.loadMocapFile <biped_ctrl> <file_name> [#prompt]

Load a motion capture (.BIP, .BVH, .CSM) file. If #prompt is specified, the file is not automatically loaded, rather the Motion Capture Conversion Parameters dialog is displayed with the specified file as the motion capture file.

-- Talent File Access Methods

biped.adjustTalentPose <biped_ctrl>

After loading a marker file, use Adjust Talent Pose to correct the biped position relative to the markers. Align the biped limbs to the markers then call biped.adjustTalentPose to compute this offset for all the loaded marker data.

Note

Calibration controls are only enabled when a marker or .bvh file is imported in its raw form. Do not use key reduction or extract footsteps when you import a marker file for the first time.

biped.saveTalentFigFile <biped_ctrl> <file_name>

After changing the biped scale in Talent Figure mode, save the changes into a .fig file. Use this file in the Motion Capture Conversion Parameters dialog to adjust marker files created by the same actor.

biped.saveTalentPoseFile <biped_ctrl> <file_name>

Save a Talent Pose adjustment as a .cal file.

Save a .cal file after adjusting the biped relative to the markers. A .cal file is used for processing marker files that require the same adjustment. A .cal file can be loaded in the Motion Capture Conversion Parameters dialog during marker file importation.

-- Layer related methods

biped.collapseAtLayer <biped_ctrl> <index>

Collapses all layers till the specified layer. All underneath should be active for this function to work. Return true if successful, otherwise false.

biped.createLayer <biped_ctrl> <index> <name>

Creates a layer at the specified position, maximum index value can be NumLayers + 1

biped.deleteLayer <biped_ctrl> <index>

Deletes the specified layer

biped.getCurrentLayer <biped_ctrl>

Returns the position of the currently active layer in the UI

biped.getLayerActive <biped_ctrl> <index>

Returns true if the specified layer is active.

biped.getLayerName <biped_ctrl> <index>

Returns the specified layer name

biped.numLayers <biped_ctrl>

Returns the number of layers

biped.setCurrentLayer <biped_ctrl> <index>

Sets the active layer in the UI to the specified layer

biped.setLayerActive <biped_ctrl> <index> <bool_val>

Sets the specified layer to active/inactive based upon the bool_val passed

biped.setLayerName <biped_ctrl> <index> <name>

Sets the specified layer name to the value passed

The following example will create a new Biped, access it's Vertical_Horizontal_Turn(Body) controller and load a specific *.Bip file:

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

Biped Controllers

Biped MaxScript Extensions


Biped Creation

The following properties and methods are applicable to any created Biped.

Constructor

biped.createNew <height_float> <angle_float> <wpos_point3> . . .

<height_float> the height of the Biped to be created

<angle_float> angle in degrees

0( will make the Biped face towards the right.

<wpos_point3> world position of the Biped. This is the position of the COM shadow.

Creation Properties

<biped>.arms Boolean Default: True

Specifies whether or not arms will be generated for the current biped.

<biped>.neckLinks Integer Default: 1

Specifies the number of links in the biped neck.

<biped>.spineLinks Integer Default: 4

Specifies the number of links in the biped spine.

<biped>.legLinks Integer Default: 3

Specifies the number of links in the biped legs.

<biped>.tailLinks Integer Default: 0

Specifies the number of links in the biped tail. A value of 0 specifies no tail.

<biped>.ponytail1Links Integer Default: 0

Specifies the number of Ponytail links.

<biped>.ponytail2Links Integer Default: 0

Specifies the number of Ponytail links.

<biped>.fingers Integer Default: 1

Specifies the number of biped fingers.

<biped>.fingerLinks Integer Default: 3

Sets the number of links per finger.

<biped>.toes Integer Default: 5

Specifies the number of biped toes.

<biped>.toeLinks Integer Default: 3

Specifies the number of links per toe.

<biped>.ankleAttach Float Default: 0.2

Specifies the right and left ankles' point of attachment along the corresponding foot block. The ankles may be placed anywhere along the center line of the foot block from the heel to the toe.

A value of 0 places the ankle attachment point at the heel. A value of 1 places the ankle attachment point at the toes.

<biped>.trianglePelvis Boolean Default: True

Select this control to create links from the upper legs to the lowest biped spine object when Physique is applied. Normally, the legs are linked to the biped pelvis object.

The pelvis area can be a problem when the mesh is deformed with Physique. Triangle Pelvis creates a more natural spline for mesh deformation.

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.

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 \

toesLink:2 ankleAttach:0.3 trianglePelvis:True

See also

Biped MAXScript Extensions


Biped Display Preferences

Biped Display Preferences Access

Displays the Biped Display Preferences dialog.

Method

biped.displayPrefsDlg <biped_ctrl>

<biped_ctrl> Controller which is attached to the transform track of the Biped root objects.

A Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller

The following example will display the Biped Display Preferences dialog:

Example:

bipObj = biped.createNew 100 100 [0,0,0]

select bipObj

bip = bipObj.transform.controller

-- Display properties

biped.displayPrefsDlg bip

See also

Biped Creation

Biped Controllers

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


biped_object : GeometryClass

This class represents the individual Biped body part and footstep nodes' baseobject.

Properties

<biped_object>.rootNode Node Default: Varies -- Read-only

The controller for the biped_object. For the COM, the controller type is Vertical_Horizontal_Turn. For footsteps, the controller type is FootSteps. For the remaining biped body parts, the controller type is BipSlave_Control.

See also

Vertical_Horizontal_Turn Matrix3 Controller

FootSteps : Matrix3 Controller

BipSlave_Control Controllers


Biped Layers

Layer Related Methods

biped.collapseAtLayer <biped_ctrl> <index_integer>

Collapses all layers till the specified layer. All underneath must be active for this function to work. Return true if successful, otherwise false.

biped.createLayer <biped_ctrl> <index_integer> <name_string>

Creates a layer at the specified position, maximum index value can be NumLayers + 1.

biped.deleteLayer <biped_ctrl> <index_integer>

Deletes the specified layer

biped.getCurrentLayer <biped_ctrl>

Returns the position of the currently active layer in the UI.

biped.getLayerActive <biped_ctrl> <index_integer>

Returns true if the specified layer is active.

biped.getLayerName <biped_ctrl> <index_integer>

Returns the specified layer name.

biped.numLayers <biped_ctrl>

Returns the number of layers.

biped.setCurrentLayer <biped_ctrl> <index_integer>

Sets the active layer in the UI to the specified layer.

biped.setLayerActive <biped_ctrl> <index_integer> <boolean_val>

Sets the specified layer to active/inactive based upon the boolean_val passed.

biped.setLayerName <biped_ctrl> <index_integer> <name_string>

Sets the specified layer name to the value passed.


Biped Node Hierarchy

biped.getNode <biped | biped_ctrl> <name | index> [link:<int_link>]

Returns the specified limbnode where the second argument can be a named limb like #larm, #rarm, #lfingers, #rfingers, #lleg, #rleg, #ltoes, #rtoes, #spine, #tail, #head, #pelvis, #footprints, #neck, #pony1, #pony2 or an integer index. . If you don't specify the link argument the top (first) node is returned. The only exception to this is for the biped COM, which does not contain any linked nodes (including itself). If the specified node does not exist, a value of undefined is returned.

The top level and their link nodes in character studio 3 are:
Index | Top Level | Link Nodes in Link Index Order
1 | L Clavicle | L Clavicle | L UpperArm | L Forearm | L Hand
2 | R Clavicle | R Clavicle | R UpperArm | R Forearm | R Hand
3 | L Finger0 | L Finger0 | L Finger01 | L Finger02 | L Finger1
 |  | L Finger11 | L Finger12 | L Finger2 | L Finger21
 |  | L Finger22 | L Finger3 | L Finger31 | L Finger32
 |  | L Finger4 | L Finger41 | L Finger42 |
4 | R Finger0 | R Finger0 | R Finger01 | R Finger02 | R Finger1
 |  | R Finger11 | R Finger12 | R Finger2 | R Finger21
 |  | R Finger22 | R Finger3 | R Finger31 | R Finger32
 |  | R Finger4 | R Finger41 | R Finger42 |
5 | L Thigh | L Thigh | L Calf | L HorseLink | L Foot
6 | R Thigh | R Thigh | R Calf | R HorseLink | R Foot
7 | L Toe0 | L Toe0 | L Toe01 | L Toe02 | L Toe1
 |  | L Toe11 | L Toe12 | L Toe2 | L Toe21
 |  | L Toe22 | L Toe3 | L Toe31 | L Toe32
 |  | L Toe4 | L Toe41 | L Toe42 |
8 | R Toe0 | R Toe0 | R Toe01 | R Toe02 | R Toe1
 |  | R Toe11 | R Toe12 | R Toe2 | R Toe21
 |  | R Toe22 | R Toe3 | R Toe31 | R Toe32
 |  | R Toe4 | R Toe41 | R Toe42 |
9 | Spine | Spine | Spine1 | Spine2 | Spine3
 |  | Spine4 |  |  |
10 | Tail | Tail | Tail1 | Tail2 | Tail3
 |  | Tail4 |  |  |
11 | Head | Head |  |  |
12 | Pelvis | Pelvis |  |  |
13 | Biped COM |  |  |  |
14 | Biped COM |  |  |  |
15 | Biped COM |  |  |  |
16 | Footsteps | Footsteps |  |  |
17 | Neck | Neck | Neck1 | Neck2 | Neck3
 |  | Neck4 |  |  |
18 | Ponytail1 | Ponytail1 | Ponytail11 | Ponytail12 | Ponytail13
 |  | Ponytail14 |  |  |
19 | Ponytail2 | Ponytail2 | Ponytail21 | Ponytail22 | Ponytail23
 |  | Ponytail24 |  |  |

Example:

bipObj = biped.createNew 100 100 [0,0,0] -- create a biped

nn = biped.maxNumNodes bipObj

nl = biped.maxNumLinks bipObj

for i = 1 to nn do

(

anode = biped.getNode bipObj i

if anode != undefined do

(

format "% :\t%\n" i anode.name

for j = 1 to nl do

(

alink = biped.getNode bipObj i link:j

if alink != undefined do

format "% : % \t%\n" i j alink.name

)

)

)

Biped Node Hierarchy related methods

biped.maxNumNodes <biped | biped_ctrl>

Maximum nodes supported by Biped. In character studio 3, this value is 19. In future versions of character studio, additional top level nodes may be present. See the desrciption of biped.getNode() for a list of the top level nodes.

biped.maxNumLinks <biped | biped_ctrl>

Maximum link nodes supported by Biped. In character studio 3 this value is 16. In future versions of character studio, additional link nodes may be present. See the desrciption of biped.getNode() for a list of the link nodes.

There are two levels of nodes in biped hierarchy, the top level ones are

L Clavicle

R Clavicle

L Thigh

R Thigh

Head

Spine

Pelvis

Footsteps

Neck

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.

biped.numPrefClips <biped_ctrl>

Returns the number of preferred clips

biped.getPrefClip <biped_ctrl> <index_integer>

Returns the name of the nth preferred clip.

biped.clearPrefClips <biped_ctrl>

Clears the preferred clip list.

biped.addPrefClip <biped_ctrl> <name_string>

Adds the clip to the preferred clip list. returns true if added, false if not added because it was already in the list.

biped.deletePrefClip <biped_ctrl> <name_string>

Deletes the named clip from the preferred clip list. Returns true is successful, false if the clip was not in the list.

biped.isPrefClip <biped_ctrl> <name_string>

Returns true if the clip is in the list, false if not.

biped.getCurrentClip <biped_ctrl>

Returns the name of the currently active clip for this biped - only relevant during a crowd solve.

The following are examples showing how the crowd system "PerFrameFn" 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


Biped Controllers

The Biped controller, referred to as "<biped_ctrl>" in this documentation, is called the Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller. This is sometimes also called the body controller because it is equivalent to the Biped's.transform.controller.

The Biped footsteps have a controller. It is referred to as "<footsteps_ctrl>" in this documentation. See Biped Footsteps 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 use the Biped Slave Controller. This type of controller is attached to the transform track.

See also

Biped Slave Controller

Biped MAXScript Extensions


Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller

This controller is attached to the transform track of the Biped root objects.

Constructor

biped_ctrl=bipobj.transform.controller

or:

<biped_ctrl>=$bip01.controller

Properties

All the following properties are get/set properties unless specified.

-- Structure properties

<biped_ctrl>.rootName String Default: BipXX,

where XX is a number

The name of the biped center of mass object. The center of mass (COM) is the root of the biped hierarchy, and is visible as a diamond shaped object in the biped pelvis area. The Root Name is appended to all the links of the biped hierarchy.

<biped_ctrl>.rootNode Node Default: Varies -- Read-only

The root node (COM) of the Biped system this biped_ctrl belongs to.

<biped_ctrl>.arms Boolean Default: True

Specifies whether or not arms will be generated for the current biped.

<biped_ctrl>.neckLinks Integer Default: 1

range: 1-5

Specifies the number of links in the biped neck.

<biped_ctrl>.spineLinks Integer Default: 4

range: 1-5

Specifies the number of links in the biped spine.

<biped_ctrl>.legLinks Integer Default: 3

range: 3-4

Specifies the number of links in the biped legs.

<biped_ctrl>.tailLinks Integer Default: 0

range: 0-5

Specifies the number of links in the biped tail. A value of 0 specifies no tail.

<biped_ctrl>.ponytail1Links Integer Default: 0

range: 0-5

Specifies the number of Ponytail links.

<biped_ctrl>.ponytail2Links Integer Default: 0

range: 0-5

Specifies the number of Ponytail links.

<biped_ctrl>.fingers Integer Default: 1

range: 0-5

Specifies the number of biped fingers.

<biped_ctrl>.fingerLinks Integer Default: 3

range: 1-3

Sets the number of links per finger.

Note: If the number of fingers is 0, fingerLinks is always equal to 1.

<biped_ctrl>.toes Integer Default: 5

range: 1-5

Specifies the number of biped toes.

<biped_ctrl>.toeLinks Integer Default: 3

range: 1-3

Specifies the number of links per toe.

<biped_ctrl>.ankleAttach Float Default: 0.2

range: 0-1

Specifies the right and left ankles' point of attachment along the corresponding foot block. The ankles may be placed anywhere along the center line of the foot block from the heel to the toe.

A value of 0 places the ankle attachment point at the heel. A value of 1 places the ankle attachment point at the toes.

<biped_ctrl>.height Float Default: Defined at creation

Sets the height of the current biped.

<biped_ctrl>.trianglePelvis Boolean Default: True

Select this control to create links from the upper legs to the lowest biped spine object when Physique is applied. Normally, the legs are linked to the biped pelvis object.

The pelvis area can be a problem when the mesh is deformed with Physique. Triangle Pelvis creates a more natural spline for mesh deformation.

-- Animation properties

<biped_ctrl>.gravAccel Float Default: 5.63855*Body height

Sets the strength of the gravitational acceleration used to calculate the biped's motion.

By default, this parameter is set to accurately simulate Newtonian gravity as found on the Earth's surface.

<biped_ctrl>.dynamicsType Integer Default: 0

range: 0-1

0 – Biped Dynamics

Keys for the center of mass Balance Factor and Dynamics Blend parameters are set to a value of 1. Biped calculates airborne trajectories and biped balance.

1 – Spline Dynamics

Create new center of mass keys using full spline interpolation.

Adapt Locks Group

Lock specified tracks to prevent automatic adjustments being made to those tracks when footsteps are moved in space or edited in time. All the locks except for Time work for footstep editing in space. Time, locks upper body keys when footsteps are edited in time (Track View). Adapt Locks only applies to a Footstep animation not a freeform animation.

When you move a footstep in space or adjust footstep timing, Biped automatically adapts existing keyframes to match the new footsteps. Adapt locks allows you to preserve the exact position of already created keys for a selected track.

Adapt Locks does not need to be on all the time. For example, if you want to raise all the footsteps along the world Z-axis, without changing the upper body position, turn on Adapt Locks Body Vertical Keys, turn on Footstep mode, select all the footsteps and move them up along the world Z-axis. The footsteps are repositioned, the legs are adapted, but the upper body retains the same motion rather than being raised with the footsteps. Now turn off Adapt Locks Body Vertical Keys, the upper body still retains its original motion.

<biped_ctrl>.adaptLockFreeform Boolean Default: False

Turn on to prevent adaptation of a freeform period in a footstep animation. The biped's position during a freeform period will not move if footsteps after the freeform period are moved further away.

<biped_ctrl>.adaptLockHorz Boolean Default: False

Turn on to prevent adaptation of body horizontal keys when footsteps are edited in space.

<biped_ctrl>.adaptLockTurn Boolean Default: False

Turn on to prevent adaptation of body turning keys when footsteps are edited in space.

<biped_ctrl>.adaptLockVert Boolean Default: False

Turn on to prevent adaptation of body vertical keys when footsteps are edited in space.

<biped_ctrl>.adaptLockLLeg Boolean Default: False

Turn on to prevent adaptation of left leg move keys (a leg move key, is a leg key between footsteps) when footsteps are edited in space.

<biped_ctrl>.adaptLockRLeg Boolean Default: False

Turn on to prevent adaptation of right leg move keys (a leg move key, is a leg key between footsteps) when footsteps are edited in space.

<biped_ctrl>.adaptLockTime Boolean Default: False

Use Adapt Locks Time to retain upper body motion while editing footstep duration in Track View. When the duration of a footstep is changed, the biped leg will adapt by re-timing the touch, plant and lift keys. The biped upper body keys will retain their exact motion.

Separate Tracks Group

By default character studio stores a finger, hand, forearm, and upper-arm key in the clavicle track. The toe, foot and calf keys are stored in the thigh track. This optimized approach to key storage works well in most cases. If you need extra tracks, turn them on for a specific biped body part.

For example, turn on Arms if you plan on extensive finger-hand animation; if an arm key is deleted, it will not affect the finger-hand keys. Notice that in Track View a transform track is now available for the first link of the thumb (stores all finger keys), hand, forearm, and upper-arm.

<biped_ctrl>.sepArmsTracks Boolean Default: False

Turn on to create separate transform tracks for the finger, hand, forearm and upper-arm.

There is one finger track per hand. All finger keys are stored in the "Finger0" transform track, the first link of the biped thumb.

<biped_ctrl>.sepLegsTracks Boolean Default: False

Turn on to create separate toe, foot, and calf transform tracks.

<biped_ctrl>.sepPonytail1Tracks Boolean Default: False

Turn on to create separate ponytail 1 transform tracks.

<biped_ctrl>.sepPonytail2Tracks Boolean Default: False

Turn on to create separate ponytail 2 transform tracks.

Note:

If the number of pony tail links is 0, you cannot set Separate Ponytail Tracks to true.

<biped_ctrl>.sepNeckTracks Boolean Default: False

Turn on to create separate transform tracks for the neck links.

<biped_ctrl>.sepTailTracks Boolean Default: True

Turn on to create separate transform tracks for each tail link.

<biped_ctrl>.sepSpineTracks Boolean Default: False

Turn on to create separate spine transform tracks.

-- Modes

<biped_ctrl>.figureMode Boolean Default: False

-- cannot be in Buffer mode to enter figureMode

Use Figure mode to fit a biped to the mesh or mesh objects representing your character. Leave Figure Mode on when you attach the mesh to the biped with Physique. Figure mode is also used to scale a biped with a mesh attached, to make biped "fit" adjustments after Physique is applied, and to correct posture in motion files that need a global posture change.

<biped_ctrl>.footstepMode Boolean Default: False

Create and edit footsteps; generate a walk, run, or jump footstep pattern; edit selected footsteps in space; and append footsteps using parameters available in Footstep mode.

<biped_ctrl>.motionMode Boolean Default: False

-- cannot be in Buffer mode to enter motionMode

Create scripts and use editable transitions to combine .bip files together (to create character animation) in Motion Flow mode. After creating a script and editing transitions, use Save Segment on the General rollout to store a script as one long .bip file. Save a .mfe file, this enables you to continue Motion Flow work in progress.

<biped_ctrl>.bufferMode Boolean Default: False

Footsteps are required in the buffer to enter bufferMode.

Edit segments of an animation in Buffer mode. Copy footsteps and associated biped keys into the buffer using Copy Footsteps on the Footstep Operation rollout first, then turn on Buffer mode to view and edit the copied segment of your animation.

Note

Paste buffered motion back to the original animation repeatedly to create looping motions.

Edit footsteps and biped animation that has been copied into the buffer using Copy Footsteps on the Footsteps Operation rollout. The changes can be pasted back by turning off Buffer Mode, turning on Paste Footsteps on the Footstep Operation rollout and overlapping the buffered footsteps with the original footsteps. The buffered motion is spliced into the original animation.

<biped_ctrl>.bendLinksMode Boolean Default: False

Bend all the biped spine objects naturally by rotating a biped spine object. Bend Links also works for the biped tail and ponytail links.

<biped_ctrl>.rubberBandMode Boolean Default: False

Use this to reposition the biped elbows and knees without moving the biped hands or feet in Figure mode. Reposition the biped center of mass to simulate the physics of wind or weight pushing against the biped. Figure mode must be turned on to enable Rubber Band Mode.

Note

Rubber Band mode behaves differently than Non-Uniform Scale. If you "Rubber Band" the biped thigh, for example, the thigh and biped calf objects scale proportionally to keep the biped foot stationary. Using Non-Uniform Scale, the calf retains its scale and the foot moves.

<biped_ctrl>.scaleStrideMode Boolean Default: True

Footstep stride length and width are scaled to match the stride length and width of the biped figure. scaling occurs automatically when you load a .bip, .stp, or .fig file. When you paste footsteps; or when you scale the biped's legs or pelvis.

<biped_ctrl>.inPlaceMode Boolean Default: False

-- cannot be in Figure mode to enter inPlaceMode

Keep the biped visible in the viewports while the animation plays. Use this for biped key editing or adjusting envelopes with Physique. Prevents XY movement of the biped center of mass during animation playback; motion along the Z-axis is preserved. In Place mode is stored with the 3ds max file.

<biped_ctrl>.inPlaceXMode Boolean Default: False

-- cannot be in Figure mode to enter inPlaceXMode

Lock center of mass X-axis motion. Use this for game export where the character stays in place but the swinging motion of the hips and upper body along the Y-axis is preserved.

<biped_ctrl>.inPlaceYMode Boolean Default: False

-- cannot be in Figure mode to enter inPlaceYMode

Lock center of mass Y-axis motion. Use this for game export where the character stays in place but the swinging motion of the hips and upper body along the X-axis is preserved.

Biped limbs, footsteps, and center of mass keys can be adjusted using In Place mode (when the center of mass is moved on the XY-axes in this mode, the footsteps move). View biped playback without requiring a follow camera. In this viewing mode, visible footsteps "slide" under the biped.

For export to games, this feature is valuable since many game engines intelligently move the character's center of mass laterally according to game play. In Place mode makes it easy to view, tune, and export animation in a manner that is complimentary to game engine playback.

Note

Trajectories do not display when In Place mode is active.

-- Track Selection

<biped_ctrl>.trackSelection Integer Default: 0

0 - No track selection

While a trackSelection value of 0 is a valid return value, setting trackSelection to 0 is meaningless and will not change the current track selection.

1 - Body Horizontal

Turn on to prevent adaptation of body horizontal keys when footsteps are edited in space.

2 - Body Vertical

Turn on to prevent adaptation of body vertical keys when footsteps are edited in space.

3 - Body Rotation

Turn on to prevent adaptation of body turning keys when footsteps are edited in space.

-- Display properties

<biped_ctrl>.displayBones Boolean Default: False

Displays biped bones. Bones are represented as yellow lines, which do not render. Selecting Bones is useful for seeing exactly where the joints fall in relation to the biped objects.

<biped_ctrl>.displayObjects Boolean Default: True

Displays biped body objects (objects).

<biped_ctrl>.displayFootsteps Boolean Default: True

Displays biped footsteps in the viewport. Footsteps are represented as green and blue foot-shaped outlines by default; these are also visible in preview renderings. Turning off the Footsteps button also turns off the footstep numbers and the center of mass shadow.

<biped_ctrl>.displayFSNumbers Boolean Default: True

Displays biped footstep numbers. Footstep numbers specify the order in which the biped will move along the path created by the footsteps. Footstep numbers are displayed in white and do not render, but do appear in preview renderings.

<biped_ctrl>.displayTrajectories Boolean Default: False

Displays trajectories for selected biped limbs.

-- Layers

<biped_ctrl>.visibleBefore Integer Default: 1

Set the number of preceding layers too display as stick figures.

<biped_ctrl>.visibleAfter Integer Default: 0

Set the number of succeeding layers too display as stick figures.

<biped_ctrl>.keyHighlight Boolean Default: False

Display keys by highlighting the stick figures.

-- Footstep related properties

<biped_ctrl>.fsAppendState Boolean Default: False

Each new footstep is appended to the end of the biped's footstep sequence.

<biped_ctrl>.fsCreateState Boolean Default: False

Set to true to create new states. The first state you add is, by default, the first state in the controller that executes when the simulation is run.

<biped_ctrl>.fsGroundDuration Time Default: 18f

<biped_ctrl>.fsAirDuration Time Default: 3f

Specifies the number of frames when the body will be in the air during a run or a jump.

Note

If fsGaitMode is #walk, the above 2 parameters are the Walk Footstep and Double Support durations, respectively. If fsGaitMode is #run, the above 2 parameters are the Run Footstep and Airborne durations, respectively. If fsGaitMode is #jump, the above 2 parameters are the 2-Feet down and Airborne durations, respectively.

<biped_ctrl>.fsGaitMode Name Default: #walk

fsGaitMode can be set to any of the three gaits: #walk, #run, #jump

-- Motion Flow properties

<biped_ctrl>.motionFlow MoFlow

Returns an instance of MoFlow. See Biped Motion Flow section for more details.

-- Motion Capture properties

<biped_ctrl>.displayBuffer Boolean Default: False

A red stick figure appears, representing the raw motion capture data.

<biped_ctrl>.displayBufferTraj Boolean Default: False

Display a trajectory based on the buffered raw motion capture data for any biped body part. Use this in combination with Show/Hide Trajectories on the Display rollout to see how closely the raw and filtered data match.

<biped_ctrl>.talentFigMode Boolean Default: False

Turn on Talent Figure mode to scale the biped relative to the markers. Calibration for the entire marker file takes place when you exit Talent Figure mode.

Keyframe adaptation takes place in order to accommodate the new biped scale; because of this, you should adjust the biped scale before adjusting the biped position relative to the markers.

Use Rubber Band Mode on the General rollout and Non-Uniform Scale to size the biped in Talent Figure mode.

Ideally, you will not need to use this feature. When loading a motion capture file, Biped attempts to extract the appropriate figure scale from the given data. Use Talent Figure mode only if the extracted scale of the biped doesn't match the scale of the original talent. Minor differences in scale will alter the motion.

Note

Calibration controls are only enabled when a marker or .bvh file is imported in its raw form. Do not use key reduction or extract footsteps when you import a marker file for the first time.

-- Object Space Object

<biped_ctrl>.osObject Node Default: Undefined

The Object Space Object for the currently selected body part. The osObject can be specified for the Clavicle or any of its decendents, and the Thigh or any of its decendents. The osObject is undefined for all other body parts. The osObject is normally specified in the IK Key Info rollout.

-- SubAnim Properties (as seen in Track View)

<biped_ctrl>.vertical Matrix3 -- Animatable

The vertical track of controller

<biped_ctrl>.horizontal Matrix3 -- Animatable

The horizontal track of controller

<biped_ctrl>.turning Matrix3 -- Animatable

The turning track of controller

<biped_ctrl>.Ease_Curve Point3 -- Animatable

Animated over range 0 to 1

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


FootSteps : Matrix3 Controller

Constructor

<footsteps_ctrl> = $'Bip01 Footsteps'.transform.controller

or:

<footsteps_ctrl>=$'Bip01 Footsteps'.controller

Notes

This controller is attached to the transform track of the named Biped footstep object.

Properties

<footsteps_ctrl>.freeFormMode Boolean Default: False

false - Edit Footsteps

true - Edit Free Form (no physics)

<footsteps_ctrl>.dispNumType Integer Default: 0

0 - Start and End Frame

1 - Start Frame

2 - Duration

3 - Double Support

<footsteps_ctrl>.dispAirDur Boolean Default: False

Displays the foot air duration. This is the number of frames each foot is in the air in the lower part of each footstep's portion of the track.

<footsteps_ctrl>.dispNoSupport Boolean Default: False

Displays the number of frames when both feet are off the ground, directly above the areas without footsteps.

<footsteps_ctrl>.rootName String Default: Varies

Contains the root name of the Biped using the Foootsteps Controller. Changing the value of this property also changes the root name of the Biped.

<footsteps_ctrl>.rootNode Node Default: Varies -- Read-only

The root node (COM) of the Biped system this footstep_ctrl belongs to.

The following example will access the footstep controller, set several values and then display all of its properties.

Example:

fsCont = $'Bip01 Footsteps'.transform.controller

fsCont.freeFormMode = true

fsCont.dispNumType = 3

fsCont.dispAirDur = false

fsCont.dispNoSupport = false

showProperties fsCont

See also

Biped Footprints

Biped Keys


Biped Slave Controller

Individual Biped body part objects and the Vertical, Horizontal, and Turning tracks of the Biped_Vertical_Horizontal_Turn_Body_Matrix3_Controller use the Biped_Slave ControllerBiped_Slave_Controller. This type of controller is attached to the transform track.

<bipslave_ctrl>=$'Bip01 Pelvis'.controller

It is not always possible to get the controller via <biped_object>.transform.controller. The transform track is not exposed for all nodes but it is possible to get the controller via: <biped_object>.controller.

Properties

<bipslave_ctrl>.rootName String Default: Varies

The name of the root node (COM) of the Biped system this bipslave_ctrl belongs to. Note: changing the value of this property also changes the root name of the biped.

<bipslave_ctrl>.rootNode Node Default: Varies -- Read-only

The root node (COM) of the Biped system this bipslave_ctrl belongs to.

See also

Biped MAXScript Extensions


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

Biped Footprints


Biped Footprints

Methods

biped.addFootprint <biped_ctrl> <matrix3> [append:<boolean>]

Specifies the position and rotation of the footstep. The scale portion of the matrix3 should always be the identity matrix ([1,1,1]).

Creates a single footprint for the biped, where matrix3 specifies the position and rotation of the footstep. The scale portion of the matrix3 should always by unity ([1,1,1]).

Notes

Creates a single footprint for the Biped.

Global Properties

biped.fsAddSide Integer Default:0

0 - Start Right

1 - Start Left

Notes

For multiple footstep creation, the starting foot needs to be identified. There is a UI radio button in the Multiple Footstep Creation dialog "Start Right/Start Left". The biped global property, fsAddSide, exposes access to this UI element.

This property also effects the start foot when manually creating footsteps in the viewports and when using biped.addFootprint. If the biped.fsAddSide is 1, a left footstep is created. If 0, a right footstep is created. When you create a footstep in the viewports or by using biped.addFootprint, the value of biped.fsAddSide is flipped, resulting in alternating footsteps being created by default.

Methods

biped.multipleFSDlg <biped_ctrl>

Displays the Multiple Footstep Creation dialog

biped.getMultipleFSParams <gait_type_name>

Returns an instance of MultFprintParams, gait_type_name can be #walk, #run or #jump. For information on MultFprintParams and gait_type_name see Biped MultFprintParams ClassBiped_MultFprintParams_Class.

The following example will obtain the MultipleFSParams for a walk cycle, set several of its values and then show all of the properties.

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

Method

biped.addMultipleFootprints <biped_ctrl> <MultFprintParams>

Create footsteps for a Biped based on the MultFprintParams value

biped.newFootprintKeys <biped_ctrl>

Activates all inactive footsteps. Activation creates default keys for any footsteps that do not have them. If a footstep does not have keys, it is displayed as bright green (right foot) or bright blue (left foot). After keys are created for the footsteps, the footsteps change color to pastel green and pastel blue.

Create Biped keys for inactive footsteps on the Biped

The following example will create a biped, create 10 footsteps and then have Biped create default keys for the footsteps.

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

Biped MultFprintParams Class

Biped MaxScript Extensions

Biped Keys


Biped Class : MultFprintParams

This class represents multiple footstep creation parameters of a Biped. An instance of this class is returned by the biped.getMultipleFSParams <gait_type_name> method, where gait_type_name can be #walk, #run or #jump.

Properties

#walk #run #jump

<MultFprintParams>.alternate Boolean Default: true true true

Footsteps will alternate between right and left. Alternate is always selected when the Walk gait is selected. You can only clear Alternate when Run or Jump gaits are selected.

<MultFprintParams>.numFootsteps Integer Default: 4 4 4

Determines the number of new footsteps to be created.

<MultFprintParams>.paramStrideWidth Float Default: 1.0 1.0 1.0

Sets the stride width as a percentage of the pelvis width. A value of 1.0 produces a stride width equal to the pelvis width. A value of 3.0 produces a wide, waddling stride. Changes to this setting automatically change the Actual Stride Width.

Parametric describes the parameter in terms of biped anatomy, and Actual describes the value in 3ds max units.

<MultFprintParams>.actualStrideWidth Float Default: 0.0 0.0 0.0

Sets the stride width in modeling units. Changes to this setting automatically change the Parametric Stride Width.

<MultFprintParams>.autoTiming Boolean Default: true true true

Sets timing parameters automatically. Auto Timing affects the following timing parameters for the Walk gait:

Walk footstep, Double Support

When Auto Timing is selected, these parameters are automatically adjusted to reasonable values. Control the footstep sequence by adjusting the Stride Length and Time to Next Footstep parameters.

When Auto Timing is cleared, you can control the footstep sequence by adjusting the gait timing parameters, but you can't change the Time to Next Footstep parameter.

<MultFprintParams>.interpTiming Boolean Default: false false false

Control acceleration or deceleration of the series of footsteps.

<MultFprintParams>.multiInsertInTime Boolean Default: false false false

false - Start after last footstep

Appends the newly created footsteps to the end of the existing footstep sequence.

true - Start at current frame

Inserts the newly created footsteps at the current frame after the existing footstep sequence allowing you to make a gap in time before the footsteps start again.

<MultFprintParams>.actualStrideLength1 Float Default: 0.0 0.0 0.0

Sets the stride length for new footsteps in 3ds max units.

<MultFprintParams>.paramStrideLength1 Float Default: 0.75 1.5 2.4

Sets the stride length for the new footsteps as a percentage of the length of the biped's leg. The default value of 0.75 gives an average stride of normal proportions.

A value of 1.0 will produce a stride length equal to the leg length, which makes the biped stretch slightly to reach the next step. A value of 0.0 will make the biped walk in place. A negative stride length will make the biped walk backwards.

When a biped walks backwards, it does not simply reverse the forward movement but maintains the correct foot-state sequence with the toe touching the ground first, followed by the heel.

Adjusting Parametric Stride Length automatically changes the value for Actual Stride Length.

<MultFprintParams>.actualStrideHeight1 Float Default: 0.0 0.0 0.0

Sets the rise or fall between footsteps. You can use this parameter to create a set of footsteps going up or down a slope or a stairway.

The value for Actual Stride Height is the difference in height in units between each of the new footsteps. Positive values step up and negative values step down.

<MultFprintParams>.cycle1 Time Default: 15f 15f 15f

<MultFprintParams>.actualStrideLength2 Float Default: 0.0 0.0 0.0

Sets the stride length for new footsteps in 3ds max units. The same rules apply as for Parametric Stride Length. Adjusting Actual Stride Length automatically changes the value for Parametric Stride Length.

<MultFprintParams>.paramStrideLength2 Float Default: 0.75 1.5 2.4

Sets the stride length for the new footsteps as a percentage of the length of the biped's leg. The default value of 0.75 gives an average stride of normal proportions.

A value of 1.0 will produce a stride length equal to the leg length, which makes the biped stretch slightly to reach the next step. A value of 0.0 will make the biped walk in place. A negative stride length will make the biped walk backwards. When a biped walks backwards, it does not simply reverse the forward movement but maintains the correct foot-state sequence with the toe touching the ground first, followed by the heel.

Adjusting Parametric Stride Length automatically changes the value for Actual Stride Length.

<MultFprintParams>.actualStrideHeight2 Float Default: 0.0 0.0 0.0

Sets the rise or fall between footsteps. You can use this parameter to create a set of footsteps going up or down a slope or a stairway.

The value for Actual Stride Height is the difference in height in units between each of the new footsteps. Positive values step up and negative values step down.

<MultFprintParams>.cycle2 Time Default: 15f 15f 15f

See the biped.addMultipleFootprints method for creating footsteps based on a MultFprintParams, and biped.newFootprintKeys creating the biped keys for the inactive footsteps.

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

Biped Slave Controller

FootSteps : Matrix3 Controller

Biped Footsteps

Biped MAXScript Extensions


BipedFSKey : MAXObject

This class represents a Biped footstep in the viewports and trackview.

Properties

<fskey>.time Time Default: Varies

A value indicating when in time the key occurs.

<fskey>.duration Time Default: Varies

The number of frames in each footstep.

<fskey>.selected Boolean Default: False

<fskey>.edgeSel Integer Default: 0

0 - no edges selected

1 - left edge Selected

2 - right edge selected

3 - both edges Selected

<fskey>.active Boolean Default: True

Activate or make inactive the footstep.

<fskey>.transform Matrix3 Default: Varies

<fskey>.side Name Default: #left or #right -- Read-only

See also

Biped Controllers

Biped Footsteps

Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller

Biped Keys

Biped MAXScript Extensions


Biped Motion Flow

MoFlow : MaxWrapper

MoFlowScript : MaxWrapper

MoFlowSnippet : MaxWrapper

MoFlowTranInfo : MaxWrapper

MoFlowTransition : MaxWrapper


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.

Properties

<moflow>.scripts Array Default: #()

-- Read-only

An array of motion flow scripts (MoFlowScript values).

A Script is a list of clips (.bip files) that are executed sequentially to animate a character.

<moflow>.activeScript MoFlowScript Default:undefined

Get/set which MoFlowScript in scripts array is the active script. If the specified MoFlowScript is not in the scripts array, no action occurs.

<moflow>.snippets Array Default: #()

-- Read-only

An array of motion flow snippets (MoFlowSnippet values).

<moflow>.selSnippets BitArray Default: #{}

A bitarray specifying the motion flow snippets that are selected in the Motion Flow Graph.

<moflow>.startFrame Integer Default: 0

-- Read-only

The start frame of currently active motion flow script.

<moflow>.endFrame Integer Default: 0

-- Read-only

The last frame of currectly active motion flow script.

Methods

loadMoFlowFile <moflow> <file_name> [ quiet:<boolean> ]

If quiet:true, which is the default, any warning message dialogs are suppressed.

Load a Motion Flow Editor file (.mfe). Motion Flow Editor files include:

Clips: references to biped animation files.

Transitions: The names, attributes, and connections between clips.

Scripts: different paths through a set of connected clips and transitions.

saveMoFlowFile <moflow> <file_name>

Save a Motion Flow Editor file (.mfe).

Load/Save a motion flow (.MFE) file.

Note

The location of the referenced .bip files is saved in the .mfe file. If the .bip file cannot be found, the program looks to the motion flow directory specified in \plugcfg\biped.ini. By default, this setting is MoFlowDir=<maxdir>\cstudio\scripts

If a referenced .bip file cannot be found in its current location, you will need to move it to the specified Motion Flow directory. You can change the location of this directory at any time by editing your biped.ini file with a text editor. The new directory will be used the next time you restart 3ds max. You can also add multiple search paths to your biped.ini file by repeating the MoFloDir= line multiple times. The program will search the directories in the order they appear and will use the first instance of the file that it finds.

loadSnippetFiles <moflow>

Loads the snippet files whose file names are assigned. This function should be called whenever new snippets are added.

Clips represent all or part of a .bip file.

addScript <moflow> <name>

Scripts represent different paths through the clips in the Motion Flow Graph.

Creates a new motion flow script with the given name and adds it to the motion flow. Returns the new MoFlowScript.

deleteScript <moflow> <MoFlowScript>

deleteScript <moflow> <index_integer>

Deletes the specified script. If the second argument is an integer, the script deleted is the indexed script in the motion flow's .scripts array.

getScriptIndex <moflow> <MoFlowScript>

Given the script, returns its index in the script's combobox.

getSnippetIndex <moflow> <MoFlowSnippet>

Given the snippet, returns its index in the in the motion flow's .snippets array.

computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]

Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network.

Related Methods

newSnippet <filename> <point2_pos> <redraw:true> <load:true>

Adds a new MoFlowSnippet to the motion flow network, from the given .bip file. <point2_pos> is the position in windows coordinates where the origin is the top left of the snippet in the motion flow graph. Redraw:true will redraw the graph window. Load:true will immediately load the snippet

See also

Biped Controllers

MoFlowScript : MaxWrapper

MoFlowSnippet : MaxWrapper

Biped MAXScript Extensions


MoFlowScript : MaxWrapper

Constructor

addScript <moflow> <script_name>

Create a new motion flow script with the given name to the motion flow. Returns the new MoFlowScript.

Properties

<MoFlowScript>.startFrame Integer Default: 0f

<MoFlowScript>.snippets Array Default: #() -- Read-only

Array of MoFlowSnippet values defined in the motion flow script

<MoFlowScript>.name String Default: Varies

<MoFlowScript>.startPos Point3 Default: [0,0,0]

<MoFlowScript>.startRot Float Default: 0

Methods

addSnippet < MoFlowScript > < MoFlowSnippet >

Adds the specified MoFlowSnippet to a motion flow script. Returns the MoFlowSnippet value.

insertSnippet < MoFlowScript > < MoFlowSnippet > <index_integer>

Inserts the snippet at the location specified and returns the new script item. Returns the MoFlowSnippet value.

deleteSnippet < MoFlowScript > <index_integer>

Deletes the indexed MoFlowSnippet from the motion flow script.

Related Methods

deleteScript <moflow> <index_integer>

Deletes the indexed MoFlowScript from the motion flow.

computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]

Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network

Notes

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.


MoFlowSnippet : MaxWrapper

Constructor

newSnippet <moflow> <filename> <point2_pos> <redraw:true> <load:true>

Adds a new MoFlowSnippet to the motion flow network, from the given .bip file. <point2_pos> is the position in windows coordinates where the origin is the top left of the snippet in the motion flow graph. Redraw:true will redraw the graph window. Load:true will immediately load the snippet. Returns the new MoFlowSnippet.

Properties

<MoFlowSnippet>.start Integer Default: 0

The start frame in the snippet file.

<MoFlowSnippet>.end Integer Default: Varies

The end frame in the snippet file.

<MoFlowSnippet>.clipName String Default: Varies

<MoFlowSnippet>.fileName String Default: Varies

<MoFlowSnippet>.pos Point2 Default: Varies

The coordinates of the snippet in the Motion Flow Graph.

<MoFlowSnippet>.active Boolean Default: True

<MoFlowSnippet>.transitions Array Default: #(MoFlowTransition : [X,X]) – read only

An array of the transitions defined for the snippet (MoFlowTransition values). The MoFlowTransition values printed show the the from and to MoFlowSnippet names.

<MoFlowSnippet>.randomStartProbability Integer Default: 100

Methods

addTransition <from_MoFlowSnippet > <to_MoFlowSnippet > <bool_optimize>

Adds a new MoFlowTransition to a motion flow Snippet. The optimize parameter acts as the "Optimize Selected Transition" in the Motion Flow Editor.

deleteTransition < MoFlowSnippet > <index_integer>

Deletes the indexed MoFlowTransition emanating from the MoFlowSnippet.

deleteTransitionTo <from_MoFlowSnippet > <to_MoFlowSnippet >

Deletes the transition that's emanating to the specified snippet.

Related Methods

addSnippet < MoFlowScript > < MoFlowSnippet >

Adds the specified MoFlowSnippet to a motion flow script. Returns the MoFlowSnippet value.

insertSnippet < MoFlowScript > < MoFlowSnippet > <index_integer>

Inserts a snippet at the location specified and returns the new script item. Returns the MoFlowSnippet value.

deleteSnippet < MoFlowScript > <index_integer>

Deletes the indexed MoFlowSnippet from the motion flow script.

loadSnippetFiles <moflow>

Loads all of the snippet files whose file names are assigned. This function should be called whenever new snippets are added.

getSnippetIndex <moflow> <MoFlowSnippet>

Given the snippet, returns its index in the motion flow's .snippets array.

computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]

Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network

Notes

Changes to the MoFlowSnippet property values do not cause an immediate update of the biped. ComputeAnimation must be called on the MoFlow value to recompute the biped motion.


MoFlowTranInfo : MaxWrapper

Constructor

addTranInfo < MoFlowTransition >

Adds a new MoFlowTranInfo to the MoFlowTransition and returns the newly created MoFlowTranInfo.

Properties

<MoFlowTranInfo>.length Integer Default: 25

The transition length in frames.

<MoFlowTranInfo>.angle Float Default: 0.0

The direction of the destination clip

<MoFlowTranInfo>.easeFrom Float Default: 0.5

<MoFlowTranInfo>.easeTo Float Default: 0.5

<MoFlowTranInfo>.sourceStart Integer Default: Varies

The start frame for the source clip

<MoFlowTranInfo>.destStart Integer Default: Varies

The start frame for the destination clip

<MoFlowTranInfo>.sourceState Boolean Default: True

false - Fixed

true - Rolling

<MoFlowTranInfo>.destState Boolean Default: True

false – Fixed

true – Rolling

<MoFlowTranInfo>.length Integer Default: 25

The transition length in frames.

<MoFlowTranInfo>.note String Default: ""

<MoFlowTranInfo>.probability Integer Default: 100

Related Methods

deleteTranInfo < MoFlowTransition > <index_integer>

Deletes the indexed MoFlowTranInfo from the MoFlowTransition. . If the MoFlowTranInfo is the only MoFlowTranInfo in MoFlowTransition, it is not deleted.

computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]

Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network

Notes

Changes to the MoFlowTranInfo property values do not cause an immediate update of the biped. ComputeAnimation must be called on the MoFlow value to recompute the biped motion.

The following example will find the transition information from the first clip (snippet) to the next in the first script defined for the Biped motion flow.

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]

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


MoFlowTransition : MaxWrapper

Constructor

addTransition <from_MoFlowSnippet > <to_MoFlowSnippet > <bool_optimize>

Adds a new MoFlowTransition from the from_MoFlowSnippet to the to_MoFlowSnippet if one doesn't already exist. The optimize parameter acts as the "Optimize Selected Transition" in the Motion Flow Editor.

Properties

<MoFlowTransition>.fromSnippet MoFlowSnippet Default: Varies

Specifies the MoFlowSnippet transitioning from.

<MoFlowTransition>.toSnippet MoFlowSnippet Default: Varies

Specifies the MoFlowSnippet transitioning to.

<MoFlowTransition>.active Boolean Default: True -- Read-only

Specifies whether the MoFlowTransition is active.

<MoFlowTransition>.selected Boolean Default: False

Specifies whether the MoFlowTransition line is selected in the Motion Flow Graph.

<MoFlowTransition>.tranInfos Array Default: #(MoFlowTranInfo : [X,X])

-- Read-only

Array of motion flow transition info blocks (MoFlowTranInfo values). The element of this array used is determined by the <mfscriptItem>.tranIndex property.

Methods

addTranInfo < MoFlowTransition >

Adds a new MoFlowTranInfo to the MoFlowTransition and returns the newly created MoFlowTranInfo.

deleteTranInfo < MoFlowTransition > <index_integer>

Deletes the indexed MoFlowTranInfo from MoFlowTransition. If the MoFlowTranInfo is the only MoFlowTranInfo in MoFlowTransition, it is not deleted.

Related Methods

deleteTransition < MoFlowSnippet > <index_integer>

Deletes the indexed MoFlowTransition emanating from the MoFlowSnippet.

deleteTransitionTo <from_MoFlowSnippet > <to_MoFlowSnippet >

Deletes the transition that's emanating to the specified snippet.

computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]

Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network

Notes

Changes to the MoFlowTransition property values do not cause an immediate update of the biped. ComputeAnimation must be called on the MoFlow value to recompute the biped motion.

See also

Biped MAXScript Extensions


Biped Keys

All common MAXScript key functions like deleteKey, selectKeys, moveKeys etc. can be used with Biped keys. The exceptions addNewKey and deleteKeys are substituted with the following methods.

Method

biped.addNewKey <biped_controller> <time> [ #select ]

<time> Adds a new key to the controller track at the time specified.

[ #select ] The new key is also selected if the #select optional argument is specified.

The value for the new key is the interpolated controller value at the specified time. The value for the new key is the interpolated controller value at that time. The new key is also selected if the #select optional argument is specified.

addNewKey() will not add a key if a key already exists at the specified time. The return value is the key located at the specified time.

Method

biped.deleteKeys <biped_controller> [ #allKeys ] [ #selection ]

[ #allKeys ]

[ #selection ]

Deletes either all keys or all selected keys from the controller. If neither #allKeys or #selection is specified, all keys are deleted.

Accessing a Biped Controller Key by Index

Accessing a Biped controller key by indexing into the .keys property of the controller returns a type of key that MAXScript does not recognize. To get a Biped controller key by index use the following method:

Method

biped.getKey ( <biped_controller> | <footstep_ctrl> ) <index>

<biped_controller>

<footstep_ctrl>

<index>

Notes

Returns an instance of BipedKey for Biped body controllers and BipedFSKey for footstep controllers. BipedKey and BipedFSKey are defined below.

Not all of the Biped elements contain a transform controller. Rather, a controller on an object typically higher in the hierarchy may store the transform key for an element. For example, the transforms for all the fingers on a hand are stored in either the Finger0 or Clavicle transform controller. This depends on whether "Separate Tracks for Arms" is set to true or false, respectively.

The following example will get the first key for each of the subcontrollers of the $Bip01 Vertical_Horizontail_Turn transform controller and show their properties. Additionally, the first key of the $Bip01 Footstep transform controller will have its properties shown.

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


BipedKey : MAXObject

All Biped vertical, horizontal, turning, and body keys are represented by this class.

Properties

<bipedkey>.time Time Default: Varies

Enter a value to specify when in time the key occurs.

<bipedkey>.selected Boolean Default: False

<bipedkey>.tension Float Default: 25.0

Controls the amount of curvature in the animation curve.

High Tension produces a linear curve. It also has a slight Ease To and Ease From effect.

Low Tension produces a very wide, rounded, curve. It also has a slight negative Ease To and Ease From effect.

<bipedkey>.continuity Float Default: 25.0

Controls the tangential property of the curve at the key. The default setting is the only value that produces a smooth animation curve through the key. All other values produce a discontinuity in the animation curve causing an abrupt change in the animation.

<bipedkey>.bias Float Default: 25.0

Controls where the animation curve occurs with respect to the key.

<bipedkey>.easeTo Float Default: 0.0

Slows the velocity of the animation curve as it approaches the key.

High Ease To causes the animation to decelerate as it approaches the key.

The default setting causes no extra deceleration.

<bipedkey>.easeFrom Float Default: 0.0

Slows the velocity of the animation curve as it leaves the key.

High Ease From causes the animation to start slow and accelerate as it leaves the key.

The default setting causes no change of the animation curve.

<bipedkey>.type Name Default: Varies

-- Read-only

Contains #vertical, #horizontal, #turning, or #body based on the key type

There are additional properties based on the type of the key:

-- #vertical

<vertkey>.z Float Default: Varies

Reposition the selected biped part in z.

<vertkey>.dynamicsBlend Float Default: 1.0

Control the amount of gravity in an airborne period, as in a running or jumping motion. This parameter has no effect on a walking motion where footsteps overlap.

<vertkey>.ballisticTension Float Default: 0.5

Control the amount of spring or tension when the biped lands or takes off from a jump or run step. The change is subtle.

A walk cycle will not activate this value. The biped has to be airborne, then the Lift and Touch vertical keys will display a Ballistic Tension value.

-- #horizontal

<horzkey>.x Float Default: Varies

Reposition the selected biped part in x.

<horzkey>.y Float Default: Varies

Reposition the selected biped part in y.

<horzkey>.balanceFactor Float Default: 1.0

Position the biped's weight anywhere along a line that extends from the center of mass to the biped's head. A value of 0 places the biped's weight at the center of mass. A value of 1 places the biped's weight above the center of mass. A value of 2 places the biped's weight in the head.

-- #body

<bodykey>.ikBlend Float Default: 0.0

Determines how forward kinematics and inverse kinematics are blended to interpolate an intermediate position.

<bodykey>.ikSpace Integer Default: 0

0 - Body

The biped limb is in biped coordinate space.

1 - Object

The biped limb is either in World coordinate space or the coordinate space of the selected object. Coordinate space can be blended between keys.

<bodykey>.ikAnkleTension Float Default: 0.0

Adjusts the precedence of the ankle joint over the knee joint. When set to 0, the knee takes precedence. When set to 1, the ankle takes precedence.

<bodykey>.ikJoinedPivot Boolean Default: True

Put the biped foot in the coordinate space of the previous key.

<bodykey>.ikPivotIndex Integer Default: 1

Index into <bodykey>.ikPivots array of active (selected) pivot

<bodykey>.ikNumPivots Integer Default: Varies – Read only

Number of pivot points in <bodykey>.ikPivots array

<bodykey>.ikPivots Array Deafult: Varies - Array of Point3 values

Array of positions of all the pivot points for the body part

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


Biped Motion Capture

All motion capture properties in Biped are global parameters and cannot be varied from Biped to Biped. Hence they are exposed as system globals residing in the mocap struct.

Properties

mocap.fsExtractionMode Integer Default: 0

0 - None: Freeform

No footsteps are extracted.

1 - On

Extract footsteps.

2 - Fit to existing

For motion data that has both footstep motion and flying, swimming, falling, or tumbling motions.

mocap.fsConversionMode Integer Default: 0

0 - No Key Reduction

Do not reduce keys. Use this on files that are already key reduced or if you want to work with all the data in a raw motion capture file.

1 - Use Key Reduction

Reduce keys for simpler key editing.

2 - Load Buffer Only

Do not apply the data to the biped, load the data to the motion capture buffer only. Use this to either compare your edited version with the original or to paste postures from the motion capture buffer to the biped in the scene.

mocap.upVector Integer Default: 2

Set the vertical axis used in the motion capture data.

0 - X

1 - Y

2 - Z

mocap.scaleFactor Float Default: 1.0

Multiply the stored talent size by this value and size the biped accordingly.

-- range: 1+

-- Footstep Extraction

mocap.fsExtractionTol Float Default: 0.05

Set the sensitivity of footstep extraction. Biped determines if the footstep is there by checking that the foot does not move beyond the distance determined by the Extraction Tolerance value. Smaller numbers are more sensitive and extract more footsteps. Value is a percentage of foot length.

-- range: 0+

mocap.fsSlidingDist Float Default: 0.0

Create a sliding footstep when positional tolerance is reached. This value is a percentage of foot length. By default the foot must slide its own distance (100), before a sliding footstep is created.

-- range: 0+

mocap.fsSlidingAngle Float Default: 0.0

Create a sliding footstep when rotational tolerance is reached. This value is in degrees. If this is set high (360 degrees), the foot must make a complete turn before a sliding footstep is created.

-- range: 0-360

mocap.fsUseVerticalTol Boolean Default: False

Turn on Z-axis Tolerance. The control filters out footsteps that do not fall within a given range of the ground plane. Use this when filtering motions, such as hopping or pitching a baseball, in which a foot may come off the ground and remain stationary, but its position is not intended as a footstep.

mocap.fsVerticalTol Float Default: 0.5

Value is a percentage of leg length

-- range: 0+

mocap.fsZLevel Float Default: 0.0

Set a Z value (ground).

mocap.fsUseFlatten Boolean Default: False

Extracted footsteps are moved to Z=0. Use this to flatten out minor differences in the height of the extracted footsteps.

-- Load Frames

mocap.startFrame Integer Default: 0

Start importing at this frame. Default is frame 0, the first frame.

mocap.endFrame Integer Default:0

Stop importing at this frame. Default is the last frame of the clip.

mocap.loop Boolean Default: False

Loop the data by the value set here.

This is relative. Succeeding loops start where the previous loop left off. The clips are not blended and may require editing unless the original clip was designed to loop.

Use this for clips designed to loop.

Note

This often works best if Footstep Extraction is tuned off.

mocap.loopFrameCount Integer Default: 0

-- range: 0+

Key Reduction Settings

Tolerance: Set the maximum angular or positional deviation for a track.

Values are in degrees for rotation tracks. Values are in units of translation for position tracks.

Minimum Key Spacing: Set the minimum number of frames between keys.

Tolerance is computed first, then Minimum Key Spacing computes further key reduction.

A Minimum Key Spacing value of 10 for the head track ensures that no two keys are closer than 10 frames for this track.

Set All: Force all tracks to the values set in these fields.

Higher values here can determine how much key reduction is possible while preserving the original motion.

Filter: Clear to prevent filtering of the motion capture data into a track. If this is cleared, there will be no key reduction for the track.

mocap.allTol Float Default: 0.0

-- range: 0+

mocap.allSpacing Integer Default: 3

-- range: 0+

mocap.allFilter Boolean Default: False

mocap.horzTol Float Default: 1.0

-- range: 0+

mocap.horzSpacing Integer Default: 3

-- range: 0+

mocap.horzFilter Boolean Default: True

mocap.rotTol Float Default: 1.0

-- range: 0+

mocap.rotSpacing Integer Default: 3

-- range: 0+

mocap.rotFilter Boolean Default: True

mocap.vertTol Float Default: 1.0

-- range: 0+

mocap.vertSpacing Integer Default: 4

-- range: 0+

mocap.vertFilter Boolean Default: True

mocap.pelvisTol Float Default: 6.0

-- range: 0+

mocap.pelvisSpacing Integer Default: 3

-- range: 0+

mocap.pelvisFilter Boolean Default: True

mocap.spineTol Float Default: 6.0

-- range: 0+

mocap.spineSpacing Integer Default: 3

-- range: 0+

mocap.spineFilter Boolean Default: True

mocap.neckTol Float Default: 6.0

-- range: 0+

mocap.neckSpacing Integer Default: 3

-- range: 0+

mocap.neckFilter Boolean Default: True

mocap.leftArmTol Float Default: 6.0

-- range: 0+

mocap.leftArmSpacing Integer Default: 3

-- range: 0+

mocap.leftArmFilter Boolean Default: True

mocap.rightArmTol Float Default: 6.0

-- range: 0+

mocap.rightArmSpacing Integer Default: 3

-- range: 0+

mocap.rightArmFilter Boolean Default: True

mocap.leftLegTol Float Default: 6.0

-- range: 0+

mocap.leftLegSpacing Integer Default: 3

-- range: 0+

mocap.leftLegFilter Boolean Default: True

mocap.rightLegTol Float Default: 6.0

-- range: 0+

mocap.rightLegSpacing Integer Default: 3

-- range: 0+

mocap.rightLegFilter Boolean Default: True

mocap.tailTol Float Default: 6.0

-- range: 0+

mocap.tailSpacing Integer Default: 3

-- range: 0+

mocap.tailFilter Boolean Default: True

-- Limb orientation

Angle: Move the knee or Elbow position to create the biped joint key.

Point: Rotate the shoulder-elbow-wrist or hip-knee-ankle to create the biped joint key.

Auto: Auto reads exact hand and foot positions from the motion capture data, character studio then places the knees and elbows in a natural position. For marker files involving running and walking, this option can clean up the data nearly instantly, regardless of how many markers were used (and where they were placed).

mocap.kneeOrient Integer Default: 0

0 - angle

1 - point

2 - auto

The biped knee hinge joints are perpendicular to the triangles formed by the hip-knee-ankle. Resolve errors in the motion capture data that break this rule by using either the angle or point method.

mocap.elbowOrient Integer Default: 0

0 - angle

1 - point

2 - auto

The biped elbow hinge joints are perpendicular to the triangles formed by the shoulder-elbow-wrist. Resolve errors in the motion capture data that break this rule by using either the angle or point method.

mocap.footOrient Integer Default: 0

0 - angle

1 - auto

The biped foot hinge joints are perpendicular to the triangles formed by the hip-knee-ankle respectively. Resolve errors in the motion capture data that break this rule by using either the angle or point method.

mocap.handOrient Integer Default: 0

0 - angle

1 - auto

The biped hand hinge joints are perpendicular to the triangles formed by the shoulder-elbow-wrist. Resolve errors in the motion capture data that break this rule by using either the angle or point method.

-- Talent Definition

mocap.talentFigStrucFile String Default: "" -- figure structure file (.fig)

A .fig file containing changes made to the biped scale while in Talent Figure mode.

mocap.useTalentFigStrucFile Boolean Default: False

Turn on useTalentFigStrucFile to use the file whose string is defined in mocap.talentFigStrucFile.

mocap.talentPoseAdjFile String Default: "" -- pose adjustment file (.cal)

A .cal file containing changes made to the biped while in Adjust Talent Pose mode.

mocap.useTalentPoseAdjFile Boolean Default: False

Turn on useTalentPoseAdjFile to use the file whose string is defined in mocap. talentPoseAdjFile.

-- Marker Name Files

mocap.markerNameFile String Default: "" -- csm marker name file (.mnm)

A Marker Name file to map incoming marker names in motion capture files (.bvh or .csm) to the character studio marker naming convention.

mocap.useMarkerNameFile Boolean Default: False

When set to true, use the file defined in mocap.markerNameFile.

mocap.jointNameFile String Default: "" -- bvh marker name file (.mnm)

A Marker Name file to map incoming marker names in motion capture files (.bvh or .csm) to the character studio marker naming convention.

mocap.useJointNameFile Boolean Default: False

When set to true, use the file defined in mocap.jointNameFile.

-- Marker Display Options

Marker and marker names are displayed around the biped. Discrepencies like the biped elbow position relative to the elbow marker can be spotted and adjusted.

mocap.dispKnownMarkers Boolean Default: False

mocap.dispKnownMarkersType Boolean Default: False

true – on all props

false – on selected props

mocap.dispPropMarkers Boolean Default: False

mocap.dispUnKnownMarkers Boolean Default: False

-- Load Save Methods

mocap.loadParameters <file_name>

mocap.saveParameters <file_name>

Load/Save a motion capture parameter (.MOC) file


MAXScript Extensions for Crowd

Crowd : Helper

Delegate:Helper

CrowdScatter:

CrowdAssignment : MAXObject

CrowdTeam : MAXObject

CrowdState:MAXObject

CrowdTransition : MAXObject

Orientation_Behavior : MAXObject

Path_Follow_Behavior : MAXObject

Scripted_Behavior : MAXObject

Seek_Behavior : MAXObject

Space_Warp_Behavior:MAXObject

Speed_Vary_Behavior : MAXObject

Surface_Follow_Behavior : MAXObject

Wander_Behavior : MAXObject

CogControl : MAXObject

MotionClips and GlobalMotionClip

See also

Biped and Crowd Interaction


Crowd : helper

Constructor

crowd ...

Properties

<crowd>.simStart Integer Default: 0

The first frame of the simulation.

<crowd>.solveStart Integer Default: 0

The frame at which you begin solving.

<crowd>.solveEnd Integer Default: 100

Specifies the last frame considered for the solution.

<Crowd>.deleteKeys Boolean Default: False

When true, Crowd deletes the keys of active delegates in the range over which the solution takes place.

<Crowd>.saveNthPos Integer Default: 1

Saves every nth position frame after the solution.

<Crowd>.saveNthRot Integer Default: 1

Saves every nth rotation frame after the solution.

<Crowd>.flashing Boolean Default: True Alias: Hilite_Delegates_During_Assignments

<crowd>.vectorScale Float Default: 1.0

Globally scales all force and velocity vectors that are displayed during the simulation. Scaling vectors up helps to see them better when they are very small. It does not effect the simulation.

<Crowd>.useScript Boolean Default: False

When true, Crowd executes a script at each frame of the solution.

<Crowd>.functionName String Default: "PerFrameFn" Alias: Script_Context_Name

The name of the function to be executed. This name must also be specified in the script.

<Crowd>.script String Default: Undefined

<crowd>.update Boolean Default: True Alias: Update_Display_During_Solve

When true, motion produced during solution of a crowd simulation appears in the viewports.

<Crowd>.updateFrequency Integer Default: 1

How often the display is updated during the solution. If 1, the update occurs every frame. If 2, the update occurs every other frame, and so on.

<Crowd>.solveForBipeds Boolean Default: False

When on, only biped/delegates are included in the computation. Also, the options to use priorities and backtracking become available. These options are available only for biped-only computations.

<Crowd>.usePriorities Boolean Default: False

When on, biped/delegates are computed one delegate at a time, in order of their Priority values, from lowest to highest. Also, backtracking becomes available and Step Solve becomes unavailable.

<Crowd>.backtracking Boolean Default: False

Turns on backtracking functionality when solving a crowd simulation that uses bipeds. When Backtracking is on during the solution, in the case of an impending collision between bipeds, the Crowd system will back up the simulation to the beginning of the current clip, and then try a different traversal of the lower-priority delegate/biped's motion flow graph. If necessary, the system will back up two or more clips.

<crowd>.showCollisions Boolean Default: False Alias: ClearColl

When true the delegates that collide are highlighted in the collision color.

<crowd>.whenToShowCollisions Integer Default: 0

0 – only during collisions - Colliding delegates are highlighted only in frames in which they actually collide.

1 – always - Colliding delegates are highlighted in frames in which they collide and all subsequent frames.

<crowd>.collisionColor Color Default: (color 255 0 0)

The color swatch indicates the color used to highlight colliding delegates.

<crowd>.IconSize Float Default: 0.0

<crowd>.behaviors ArrayParameter Default: #()

Array of Behavior objects

<crowd>.teams ArrayParameter Default: #()

Array of Team objects

<crowd>.assignments ArrayParameter Default: #()

<crowd>.cogcontrols ArrayParameter Default: #() Alias: Cognitive_Controllers

CogControl : MAXObject

<crowd>.scatter MAXObject Default: Scatter_Parameters

CrowdScatter:

<crowd>.objAssoc MAXRefTarg Default: ObjAssoc Alias: Object_Delegate_Associations_Parameters

Display the dialog to link any number of delegate-object pairs.

<crowd>.smooth MAXRefTarg Default: Smooth Alias: Smoothing_Parameters

Display the Smoothing dialog to smooth existing animation keys on a solved simulation to create more natural-looking animation

<Crowd>.priority MAXRefTarg Default: Priority -- Read-only; Alias: Priority_Parameters

See also

Priority Properties

Biped and Crowd Interaction


Delegate : Helper

The Delegate helper object is a special pyramidal object used in crowd animation. By default, the point of the pyramid indicates the forward direction.

The Crowd object controls the delegate or delegates, whose motion can then be imparted to a biped or other object.

Constructor

Delegate ...

CrowdDelegate ...

Properties

<Delegate>.width Float Default: 0.0 -- world units

The width of the Delegate object.

<Delegate>.depth Float Default: 0.0 -- world units

The depth of the Delegate object.

<Delegate>.height Float Default: 0.0 -- world units

The height of the Delegate object.

<Delegate>.velocityColor Color Default: (color 0 0 0)

When showVelocity is true, uses the specified color to draw a vector in the delegate's center during the simulation solution. The vector length indicates the delegate's relative speed.

<Delegate>.active Boolean Default: True

The delegate object is subject to control by a Crowd object.

<Delegate>.showForces Boolean Default: True

The forces being applied to a delegate by any applicable behaviors are drawn as vectors whose length indicate the extent of the forces. For example, if the delegate is affected by a Space Warp behavior and a Wander behavior, the vectors (using default colors) are yellow and blue-green, respectively. These vectors are visible only during solution of the crowd simulation.

<Delegate>.showVelocity Boolean Default: False

Uses the Velocity Color (see above) to draw a vector whose length depicts the delegate's relative speed. This vector is visible only during solution of the crowd simulation.

<Delegate>.showCogStates Boolean Default: True

During a solve, a text label appears next to the delegate showing the name of the cognitive controller state or transition that currently directs its behavior, if any.

<Delegate>.xyConstrain Boolean Default: True

The delegate remains at its initial height (position on the world XY axis) throughout the simulation. When off, the delegate's height can change during the simulation, for example when seeking an object at a different height.

<Delegate>.useHierBbox Boolean Default: True

Alias Use_Hierarchy_in_Bounding_Box_Computation

When true, the Avoid behavior uses the bounding box of the delegate and all of its children to perform its behavior.

This bounding box is computed by the Crowd object, is used by the collision detector, and can be accessed by other behaviors.

<Delegate>.averageSpeed Float Default: 5.0 -- animatable; world units

Specifies the delegate's baseline velocity in 3ds max units (or the current unit type) per second. This can be modified during the simulation by a variety of factors, such as a linked biped's built-in speed and Deviation settings in a behavior.

<Delegate>.maxAccel Float Default: 0.1 -- animatable; world units

Multiplied times Average Speed to determine the maximum acceleration.

<Delegate>.turnDecel Float Default: 0.3 -- animatable; Alias: Turn_Deceleration_Weight

Specifies how much a delegate should slow down when turning. The higher this setting, the more the delegate slows down when it reaches the turn angle (see following parameter). A value of 0 specifies no slowdown; a value of 1 tells the delegate to stop.

The algorithm computes a value, d, which goes linearly from 0 to (1 - Decel Weight) as the turn angle of the delegate goes from 0 to the Turn Angle specified by the user. The speed of the delegate is then multiplied by d. For example, when the delegate turns at the Turn Angle or greater, its speed will be multiplied by 1 - Decel Weight, slowing it down as much as possible based on this parameter. When the delegate is not turning at all, its speed is not affected by the Decel Weight. When the delegate is turning at half the specified Turn Angle, d = Decel Weight / 2, so its speed will be multiplied by (1 - Decel Weight / 2).

As a practical example, take a delegate traveling at 10 units/sec, Decel Weight is set to 0.4, and At Turn Angle is set to 30. When the delegate has turned 15 degrees (half the At Turn Angle), the effective deceleration weight is 0.2. Subtract that quantity from 1 to get 0.8, and then multiply that times the delegate's speed to get 8 units per second halfway into the turn. At the full turn (30 degrees), the delegate travels at 6 units per second.

<Delegate>.turnDecelAngle Float Default: 10.0 -- animatable; Alias: Turn_Deceleration_Angle

Specifies the turn angle at which Decel Weight's full slowdown effect is applied. If the current turn angle is less than At Turn Angle, the algorithm divides the latter by the former, and then divides the Decel Weight setting by the result to derive the effective decel weight.

<Delegate>.inclineDecel Float Default: 0.1 -- animatable; Alias: Incline_Deceleration_Weight

Specifies how much the delegate should slow down when moving at an upward slant.

<Delegate>.inclineDecelAngle Float Default: 90.0 -- animatable; Alias: Incline_Deceleration_Angle

Specifies the upward slant angle at which Decel Weight's full slowdown effect is applied.

<Delegate>.declineAccel Float Default: 0.1 -- animatable; Alias: Decline_Acceleration_Weight

Specifies how much the delegate should speed up when moving at a downward slant.

See Decel Weight for a full explanation, taking into account that Accel Weight produces a speedup effect rather than a slowdown. Thus, the effective acceleration weight is added to 1, not subtracted from it.

<Delegate>.declineAccelAngle Float Default: 90.0 -- animatable; Alias: Decline_Acceleration_Angle

Specifies the downward slant angle at which Accel Weight's full speedup effect is applied.

<Delegate>.maxTurnVel Float Default: 30.0 -- animatable; Alias: Max_Turn_Velocity

Specifies the maximum number of degrees a delegate can turn.

<Delegate>.maxTurnAccel Float Default: 3.0 -- animatable; Alias: Max_Turn_Acceleration

Specifies how much the delegate's turn angle can change per frame. If this is not small, the delegate's direction might jerk around. It would be allowed to turn suddenly, rather than smoothly.

<Delegate>.maxIncline Float Default: 90.0 -- animatable; Alias: Max_Incline_Velocity

Specifies the maximum number of degrees a delegate can turn upward per frame.

<Delegate>.maxDecline Float Default: 90.0 -- animatable; Alias: Max_Decline_Velocity

Specifies the maximum number of degrees a delegate can turn downward per frame.

<Delegate>.maxBank Float Default: 30.0 -- animatable

Specifies the maximum number of degrees a delegate can bank.

<Delegate>.maxBankVel Float Default: 3.0 -- animatable; Alias: Max_Bank_Velocity

Specifies how much the delegate's bank angle can change per frame.

<Delegate>.bankPerTurn Float Default: 1.0 -- animatable

The number of degrees the delegate will bank as a function of the turn angle at the current frame. For example, if Bank per Turn=1, the delegate will bank one degree for every degree it is turning at a given frame.

<Delegate>.useBiped Boolean Default: False

When true, the delegate is associated with a biped.

<Delegate>.biped Node Default: Undefined

The biped with which the delegate is associated.

<Delegate>.startFrame Integer Default: 0

The frame at which the associated biped's first clip will begin to play.

<Delegate>.priority Integer Default: 0

Sets the delegate priority, which determines the order of solution in biped/delegate simulations.

<Delegate>.startClip Integer Default: 0

0 – First clip of current script

1 – Random start clip

<Delegate>.duration Integer Default: 0

The number of frames the delegate has been in the current state.

<Delegate>.behaviors ArrayParameter Default: #()

The behaviors property contains valid values only during a solve. Contains the behaviors being used during the solve.

<Delegate>.weights ArrayParameter Default: #()

The weights property contains valid values only during a solve. Each element contains the weight of the corresponding behavior in the behaviors property value.

<Delegate>.simpos Point3 Default: [0,0,0]

The simpos property contains a valid value only during a solve. Contains the current position of the delegate during the simulation.

<Delegate>.randID Integer Default: 0

A possibly non-unique identifier whose purpose is to be used by behaviors as part of it's seed calculation. If more than one delegate has the the same randId then they should have the same random behavior. By defualt, crowd creates unique randIds.

<Delegate>.index Integer Default: -1 -- Read-only

Index used by various behaviors as indices into internal arrays. Before a solve, Crowd makes sure that the delegates who are participating in the solve are given a contiguous set of indices, so that behaviors can set up arrays which use these indices.

Related Delegates Methods

delegates.isComputing <delegate_node>

Returns a '1' if the delegate is currently active in a crowd solve simulation, it returns a '0' otherwise.

delegates.velocity <delegate_node>

Returns the normalized velocity of the delegate at the current simulation frame as a Point3 value.

delegates.prevVelocity <delegate_node>

Returns the normalized velocity of the delegate at the previous simulation frame as a Point3 value.

delegates.startVelocity <delegate_node> <time>

Returns the normalized velocity of the delegate at the start of the crowd simulation as a Point3 value. Thus the <time> parameter is a time value that should be equal to crowd.simStart.

delegates.speed <delegate_node>

Returns the speed of the delegate at the current simulation frame as a float.

delegates.isAssignmentActive <delegate_node> <assignmentIndex> <time>

Returns a '1' if the delegate is active for a particular crowd assignment at the time specified, if not it returns a '0'. The <assignmentIndex> directly corresponds to the index of the assignment in the crowds.assignment array.

Note

The functions lineDisplay ,sphereDisplay ,bboxDisplay , and textDisplay are all functions which can be used to draw a graphic primitive for a particular delegate when the crowd simulation is being solved. All of the positional values are in world space. Usually these functions will be used within a scripted behavior to visually demonstrate the behavior. For example, lineDisplay could be used to draw a line that represents the force that the behavior is exerting on that delegate.

delegates.lineDisplay <delegate_node> <startPosition> <endPosition> <color> <vectorScale>

This function will draw a line from the start position to the endPosition with the color specified .

<startPosition> is a point3 value.

<endPositions> is a point3 value.

<color> is a color value.

<vectorScale> boolean value. Whether or not to scale the line display by the Crowd.vectorScale value.

delegates.sphereDisplay <delegate_node> <position> <radius> <color>

This function will draw a sphere at the position <position>, with a radius of size <radius>, and a color of <color>. <position> is a point3 value, radius is a float and <color> is a color value.

delegates.bboxDisplay <delegate_node> <minPosition> <maxPosition> <color>

This function will draw a bounding box specifed by the two extrema points, <minPosition> and <maxPosition>, with the color specified. <minPosition> and <maxPosition> are point3 values and <color> is a color value.

delegates.textDisplay <delegate_node> <position> <color> <string>

This function will draw the text found in the <string> parameter at the position specified at <position>, with the color found in <color>. <position> is a point3 value, <color> is a color value, and <string> is a string value.

delegates.simTransform <delegate> <time>

Returns the delegate's transformation matrix at the specified time as a Matrix3 value. This method returns valid values during a solve.

Note

During a Solve, the simulation doesn't set the delegate nodes' position and rotation keys until the simulation stops. As such, accessing the delegate nodes' position and rotation during the solve will return incorrect results. The position of a delegate during a solve can be accessed via the .simpos property.

Delegates cannot be rendered, so the size of the Delegate object is primarily for use in scene setup and for determining bounding box extents.

See also

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


CrowdScatter

These properties correspond to the Scatter Objects dialog displayed by clicking the Scatter Objects icon.

Clone Tab Properties

<crowd.scatter>.cloneObject Node Default: Undefined

Object in the scene to be cloned.

<crowd.scatter>.numClones Integer Default: 10

The number of clones to be generated.

<crowd.scatter>.cloneType Integer Default: 0 Alias (0_copy__1_reference__2_instance)

0 - copy

1 - Instance

2 - Reference

Specify how the object is cloned. It can be cloned as a copy, an instance, or a reference.

<crowd.scatter>.cloneHierarchy Boolean Default: True

When true, all objects linked to the selected object are cloned as well, with the hierarchical structure retained intact for each clone.

<crowd.scatter>.cloneControllers Boolean Default: True

Set true to clone an object when calling Scatter All. The object is cloned and then any specified transforms are applied to the clones.

Position Tab Properties

<crowd.scatter>.positionSpace Integer Default: 0 Alias 0_Grid__1_Box___2_Sphere__3_Surface

0 - On Grid

1 - Inside Box

2 - Inside Sphere

3 - On Surface

4 - In Radial Area

Choose position object before selecting the reference object. On Grid distributes the clones over the surface of a grid object. Inside Box and Inside Sphere distribute the clones within the volume of a primitive box or sphere object, respectively.

<crowd.scatter>.positionObject Node Default: Undefined Alias: Grid_Box_Sphere_Surface

An object in the scene to be used as a reference object.

Note

You can use only a primitive sphere, a primitive box, or a grid helper object as a reference object. A primitive sphere or box that has been converted to a editable mesh object can't be used as a reference object.

<Crowd.scatter>.surfaceOffset Float Default: 0.0

On Surface specifies a consistent distance above the surface using surface normals for distribution. Available only when .positionSpace is set to On Surface.

<Crowd.scatter>.centerX Float Default: 0.0

Specifies the X value for the center of the distribution in world coordinates.

<Crowd.scatter>.centerY Float Default: 0.0

Specifies the Y value for the center of the distribution in world coordinates.

<Crowd.scatter>.centerZ Float Default: 0.0

Specifies the Z value for the center of the distribution in world coordinates.

<Crowd.scatter>.radius Float Default: 10.0

Specifies the maximum distance from the center within which clones are to be positioned.

<Crowd.scatter>.XYPlane Boolean Default: False

Specifies that clones are to be distributed on the world XY plane only, resulting in a disc-like array.

<crowd.scatter>.childBbox Boolean Default: True Alias: Include_childrens__bounding_boxes_in_spacing_calculations

When true, all of a hierarchical object's sub-objects are considered when determining spacing. When false, only the selected object is considered.

<crowd.scatter>.spacing Float Default: 1.0 Alias: Bounding_Box_Multiplier_for_Position_Spacing

Specifies the minimum distance between cloned objects. The Spacing setting is multiplied by the size of the object's bounding sphere to determine how close objects can get. If Spacing is left at 1.0, the default, objects normally cannot be positioned within each others' bounding spheres. If Spacing is set to 2.0, objects are separated by a distance equal to or greater than the size of the bounding sphere.

<crowd.scatter>.positionSeed Integer Default: 0

Specifies a seed value for randomizing the clones' locations. If a scene has more than one crowd, each should use a different seed to avoid having identical configurations.

Rotation Tab Properties

<Crowd.scatter>.forwardAxisSign Boolean Default: True

If true, the forward axis is in the positive direction. If false the forward axis is in the negative direction.

<crowd.scatter>.forwardAxis Integer Default: 1

0 - X

1 - Y

2 - Z

Specifies which axis of the cloned objects points forward, for use with the Look At Target option.

<crowd.scatter>.UpAxisSign Boolean Default: True

If true the up axis is in the positive direction. If false the up axis is in the negative direction.

<crowd.scatter>.UpAxis Integer Default: 2

0 - X

1 - Y

2 - Z

Axis of the cloned objects points upward; this axis is aligned with the world Z axis.

Note

You cannot specify the same axis as Local Forward and Local Up simultaneously. If you choose an axis for one that's already chosen for the other, the software switches the other to a different axis.

<crowd.scatter>.lookFrom Integer Default: 0

0 - Look From Self

1 - Look From Selected Object

Determines the direction from which the clones look. By default, each clone looks from its own position (Self), so that when several clones are looking at a single target, each is oriented differently. To orient each clone so that it's parallel to an imaginary line between two objects (the "from" object and the "to" object), choose Selected Object and specify the object with the (None) button.

<crowd.scatter>.lookFromObject Node Default: Undefined

An object from which the clones are to look if lookFrom = 1.

<crowds.scatter>.LookTowards Integer Default: 0

0 - Look Toward Self

1 - Look Toward Selected Object

Determines the direction toward which the scatter objects look. By default, each object retains its current orientation.

<crowd.scatter>.lookAtTarget Node Default: Undefined

An object toward which the clones are to look.

<crowd.scatter>.sideDeviation Float Default: 0.0

Sets a maximum deviation angle in degrees for the clones' sideways orientation. If clones should look in an object's general direction but may look at a spot to either side of the target, use Sideways Deviation to set the maximum amount by which they can deviate from the calculated angle. The actual deviation amount for each clone is calculated at random, based on the Deviation settings and the Rand Seed setting. Range=0.0 to 180.0.

<crowd.scatter>.upDownDeviation Float Default: 0.0

Sets a maximum deviation angle in degrees for the clones' up/down orientation. If clones should look in an object's general direction but may look at a spot above or below the target, use Up/Down Deviation to set the maximum amount by which they can deviate from the calculated angle. The actual deviation amount for each clone is calculated at random, based on the Deviation settings and the Rand Seed setting. Range=0.0 to 180.0.

<crowd.scatter>.rotationSeed Integer Default: 0

Specifies a seed value for randomizing the clones' orientations, based on the Deviation settings. If a scene has more than one crowd, each should use a different seed to avoid having identical configurations.

Scale Tab Properties

Contains options for scaling object clones. For each scaling axis you can specify alternative forward and up axes, plus a target object toward which the clones will point. In addition, you can specify a source object; when using both source and target objects, the clones are rotated so they're parallel to the line between the two.

<crowd.scatter>.xScale Float Default: 1.0

Sets scaling on the X axis as a multiplier.

<crowd.scatter>.xScaleDeviation Float Default: 0.0

Sets the maximum factor for randomization of scaling. For each clone, Deviation is multiplied by a random number between 0.0 and 1.0, and then added to the Scale multiplier.

<crowd.scatter>.matchXtoYscale Boolean Default: False

Lets you use the same scaling as on the Y axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable.

<crowd.scatter>.matchXtoZscale Boolean Default: False

Lets you use the same scaling as on the Z axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable.

<crowd.scatter>.yScale Float Default: 1.0

Sets scaling on the Y axis as a multiplier.

<crowd.scatter>.yScaleDeviation Float Default: 0.0

Sets the maximum factor for randomization of scaling. For each clone, Deviation is multiplied by a random number between 0.0 and 1.0, and then added to the Scale multiplier.

<crowd.scatter>.matchYtoXscale Boolean Default: False

Lets you use the same scaling as on the X axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable

<crowd.scatter>.matchYtoZscale Boolean Default: False

Lets you use the same scaling as on the Z axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable

<crowd.scatter>.zScale Float Default: 1.0

Sets scaling on the Z axis as a multiplier.

<crowd.scatter>.zScaleDeviation Float Default: 0.0

Sets the maximum factor for randomization of scaling. For each clone, Deviation is multiplied by a random number between 0.0 and 1.0, and then added to the Scale multiplier.

<crowd.scatter>.matchZtoXScale Boolean Default: False

Lets you use the same scaling as on the X axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable.

<crowd.scatter>.matchZtoYScale Boolean Default: False

Lets you use the same scaling as on the Y axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable.

<crowd.scatter>.scaleSeed Integer Default: 0

Specifies a seed value for randomizing the clones' scales, based on the Deviation settings.

All Ops Tab Properties

<crowd.scatter>.ComputeClones Boolean Default: False

Set true to clone an object when calling Scatter All. The object is cloned, then any specified transforms are applied to the clones.

Turning on Clones makes the Select Objects to Transform button unavailable. The object to clone and cloning parameters must be specified on the with .ComputeClone.

<crowd.scatter>.ComputePositions Boolean Default: False

When true and crowds.scatterall is called, the transforms are applied according to the settings in the Position panel.

<crowd.scatter>.ComputeRotations Boolean Default: False

When true and crowds.scatterall is called, the transforms are applied according to the settings in the Rotation panel.

<crowd.scatter>.ComputeScales Boolean Default: False

When true and crowds.scatterall is called, the transforms are applied according to the settings in the Scale panel.

<Crowd.scatter>.IncPosSeed Boolean Default: False

When true, add 1 to the .positionSeed value, and redistributes the objects using the new random seed.

<Crowd.scatter>.IncRotSeed Boolean Default: False

When true, add 1 to the .rotationSeed value, and redistributes the objects using the new random seed.

<Crowd.scatter>.IncSclSeed Boolean Default: False

When true, add 1 to the .scaleSeed value, and redistributes the objects using the new random seed.

<crowd.scatter>.ObjectsToScatter ArrayParameter Default: #()

Objects to be affected by calling crowds.scatterall

ObjAssoc Properties

These properties correspond to the Object / Delegate dialog displayed by clicking the Associate Objects with Delegates icon.

<ObjAssoc>.objects ArrayParameter Default: #() -- node array

Array of linked Objects.

<ObjAssoc>.delegates ArrayParameter Default: #() -- node array

Array of linked delegates.

<ObjAssoc>.alignScale Boolean Default: True

When true, Align Objects with Delegates sets each object's absolute scaling factor to that of its corresponding delegates. This is useful if, for example, you've randomized delegates' sizes with the Scatter Objects Scale panel, and want the associated objects to match.

Smooth Properties

These properties correspond to the Smoothing dialog displayed by clicking the Smooth Paths button in the Solve rollout.

<Crowd.smooth>.objects ArrayParameter Default: #() -- node array; Alias: Objects_to_Smooth

Specify which objects' positions and/or rotations to smooth.

<Crowd.smooth>.filterDelegates Boolean Default: True Alias: Filter_Delegate_Selection

When true, the Select dialog opened by the Select Objects to Smooth button shows only delegates. When off, it shows all scene objects.

<Crowd.smooth>.wholeAnim Integer Default: 0

0 - Whole Animation: Smoothes all animation frames.

1 - Animation Segment: Smoothes only the frame ranges specified in the From and To fields.

<Crowd.smooth>.from Integer Default: 0 Alias: smooth_from_frame

When Animation Segment is chosen, specifies the first animation frame for smoothing.

<Crowd.smooth>.to Integer Default: 0 Alias: smooth_to_frame

When Animation Segment is chosen, specifies the last animation frame for smoothing.

<Crowd.smooth>.positions Boolean Default: True Alias: Smooth_positions

When true, selected objects' animation paths generated via the simulation are smoothed after the simulation has finished.

<Crowd.smooth>.rotations Boolean Default: True Alias: Smooth_rotations

When true, selected objects' rotations generated via the simulation are smoothed after the simulation has finished.


CrowdAssignment : MAXObject

Constructor

CrowdAssignment ...

Properties

<crowdassignment>.team CrowdTeam Default: Undefined

A named group of delegates.

<crowdassignment>.delegate Node Default: Undefined

A delegate object. See CrowdDelegate : Helper.

<crowdassignment>.behavior MAXObject Default: Undefined

One of the Crowd Behavior classes.

<crowdassignment>.cogcontrol CogControl Default: Undefined Alias: CognitiveController

A cognitive controller. See CogControl:MAXObject for more details.

<crowdassignment>.weight Float Default: 1.0 -- animatable

The relative effect of the assigned behavior or cognitive controller. The higher an assignment's weight setting is than others', the more effect it will have. This setting is animatable. Range=0.0 to 1.0.

<crowdassignment>.active : Boolean

When true, the assignment is currently in effect. When false, the assignment has no effect. Default=true.

Notes

Normally either the team or the delegate property will contain a value of undefined. If both properties contain a value other than undefined, the assigment is applied to the team.

Normally either the cogcontrol or the behavior property will contain a value of undefined. If both properties contain a value other than undefined, the behavior will be used.

Do not assign a value other than undefined or a CrowdTeam value to the team property.

Do not assign a value other than undefined or a Behavior value to the behavior property.

Do not assign a value other than undefined or a CogControl value to the cogcontrol property.

Do not assign a node type other than a Delegate node to the delegate property.

See also

CrowdTeam : MAXObject

Crowd Behaviors

CogControl : MAXObject

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


CrowdTeam : ReferenceTarget

Constructor

CrowdTeam ...

CrowdGroup ...

Properties

<crowdteam>.name String Default: "CrowdTeam"

The default team name is Team followed by number one more than the last added team.

<crowdteam>.members ArrayParameter Default: #() -- array of Delegate nodes

Participants of the current team.

Notes

You can perform the following MAXScript operations

deleteitem <array> <itemnumber>

<array> = #(item,item...)

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.

<CrowdTeam>.members -- array of Delegate nodes

Notes

The following MAXScript operations will cause Crowd to fail, either right away or later:

NEVER set a Members ArrayParameter element to undefined.

Assigning a non-Delegate node to the Members ArrayParameter.

See also

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


CrowdState:ReferenceTarget

Constructor

CrowdState ...

Properties

<crowdstate>.name String Default: "State"

The name of the state.

<crowdstate>.behaviors ArrayParameter Default: #() -- array of behaviors

See Notes below.

The names of all behaviors associated with the state.

<crowdstate>.weights ArrayParameter Default: #() -- array of floats

See Notes below.

Specifies the selected behavior's weight. The higher the weight in relation to other behaviors' weights, the more evident the results of the behavior in the state. Default=1.0. Range=0.0 to 1.0.

<crowdstate>.transitions ArrayParameter Default: #() -- array of CrowdTransition objects

See Notes below.

Notes

You can perform the following MAXScript operations:

deleteitem <array> <itemnumber>

<array> = #(item,item...)

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.

<CrowdState>.behaviors -- array of behaviors

<CrowdState>.weights -- array of floats

<CrowdState>.transitions -- array of CrowdTransition objects

If you add or delete elements to the Behaviors ArrayParameter, the corresponding element in the Weights ArrayParameter must be added or deleted.

The following MAXScript operations will cause Crowd to fail, either right away or later:

NEVER set Behavior ArrayParameter element to undefined.

NEVER set a Behavior ArrayParameter element to anything other than an object of the appropriate type.

See also

Crowd Behaviors

CrowdTransition : MAXObject

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


CrowdTransition : MAXObject

Constructor

CrowdTransition ...

Transition ...

Properties

<crowdtransition>.priority Integer Default: 0

Sets the transition's priority.

<crowdtransition>.duration Integer Default: 25

The number of frames the software takes to affect the transition between states.

<crowdtransition>.easeIn Float Default: 0.5

Ease in value for the source clip.

<crowdtransition>.easeOut Float Default: 0.5

Ease out value for the destination clip.

<crowdtransition>.functionName String Default: "transFunc" Alias: Script_Context_Name

The name of the MAXScript conditional that specifies when/how the transition is to occur.

<crowdtransition>.script String Default: Undefined

<crowdtransition>.from CrowdState Default: Undefined Alias: FromState

The state that the transition originated from.

<crowdtransition>.to CrowdState Default: Undefined Alias: ToState

The state that the transition is destined for.

Notes

The <CrowdTransition>.functionName value must match the name of the function defined in <CrowdTransition>.script.

The script function is compiled with the function name in global scope. The function name cannot be the same as a MAXScript-defined global variable name.

The <CrowdTransition>.script is of the form:

fn transFunc del trans t =

( if t < 50 then 0 else 1

)

where del is the delegate node, trans is the CrowdTransition value, and t is the time value of the frame being evaluated. The 3ds max time context will also be frame being evaluated. The return value must be an integer value. If the return value is 0, the transition is not taken. For any other return value, the transition is taken.

The <CrowdTransition>.script is not evaluated for a delegate while the delegate is in transition between states.

The following MAXScript operations will cause Crowd to fail, either right away or later:

NEVER set the from or to properties to undefined.

NEVER set the from or to properties to anything other than a CrowdState object.

See also

CrowdState : MAXObject

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Crowds - Methods

crowds.solve <crowd_node>

Equivalent to clicking Solve in the crowd's Solve rollout. .solve starts the solving, based on all other current crowd parameter settings.

crowds.genclones <crowd_node>

Equivalent to clicking Generate Clones in the Scatter Objects dialog, Clone tab, displayed by clicking the Scatter Objects icon. Generates clones based on all other current crowd parameter settings.

crowds.genlocations <crowd_node>

Equivalent to clicking Generate Locations in the Scatter Objects dialog, Position tab, displayed by clicking the Scatter Objects icon. Generates locations based on all other current crowd parameter settings.

crowds.genrotations <crowd_node>

Equivalent to clicking Generate Orientations in the Scatter Objects dialog, Rotation tab, displayed by clicking the Scatter Objects icon. Generates rotations based on all other current crowd parameter settings.

crowds.genscales <crowd_node>

Equivalent to clicking Generate Scales in the Scatter Objects dialog, Scale tab, displayed by clicking the Scatter Objects icon. Generates scales based on all other current crowd parameter settings.

crowds.scatterall <crowd_node>

Equivalent to clicking Scatter button in the Scatter Objects dialog, All Ops tab. Scatters objects based on all other current crowd parameter settings.

crowds.alignObjects <crowd_node>

Equivalent to clicking Align Objects with Delegates in the Object / Delegates dialog displayed by clicking the Associate Objects with Delegates icon. Aligns objects based on all other current crowd parameter settings.

crowds.linkObjects <crowd_node>

Equivalent to clicking Link Objects to Delegates in the Object / Delegates dialog displayed by clicking the Associate Objects with Delegates icon. Links objects based on all other current crowd parameter settings.

crowds.assignControllers <crowd_node>

Equivalent to clicking Assign Delegate Controllers to Objects in the Object / Delegates dialog displayed by clicking the Associate Objects with Delegates icon. Assigns controllers based on all other current crowd parameter settings.

crowds.smooth <crowd_node>

Equivalent to clicking OK in the Smoothing dialog displayed by clicking the Smooth Paths button in the Solve rollout. Smooths objects motions based on all other current crowd parameter settings.

crowds.assignGridProximityPriorities <crowd_node>

Equivalent to clicking Proximity to a Grid / Assign in the Priority rollout. Assigns priorities to the delegates specified in <Crowd.priority>.delegates based on their distance from the grid specified in <Crowd.priority>.grid.

crowds.assignObjectProximityPriorities <crowd_node>

Equivalent to clicking Proximity to an Object / Assign in the Priority rollout. Assigns priorities to the delegates specified in <Crowd.priority>.delegates based on their distance from the object specified in <Crowd.priority>.object.

crowds.assignRandomPriorities <crowd_node>

Equivalent to clicking Assign Random Priorities in the Priority rollout. Assigns random priorities to the delegates specified in <Crowd.priority>.delegates.

crowds.assignUniquePriorities <crowd_node>

Equivalent to clicking Make Priorities Unique in the Priority rollout. Ensures that the priorities of the delegates specified in <Crowd.priority>.delegates are unique. If two delegates share the same priority, one of them will be given a new priority.

crowds.incrementPriorities <crowd_node>

Equivalent to clicking Increment Priorities in the Priority rollout. Increments the priorities of the delegates specified in <Crowd.priority>.delegates by the value in <Crowd.priority>.increment.

Notes - MAXScript Group

The MAXScript group of the Solve Rollout has a feature to control the execution of a MAXScript script at each frame.

Use MAXScript: When on, a user-specified script is executed at each frame during the solution. Default=off.

Function Name: The name of the function to be executed. This name must be identical to the one specified in the script.

Edit MAXScript: Click this button to open a MAXScript window for displaying and modifying the script.

The crowd function needs two parameters defined. The 1st parameter passed in is the current crowd and the 2nd parameter passed in is the solve frame.

Here is simple example:

fn g_PerFrameFn current_crowd the_frame_time =

(

if the_frame_time == 1f then

(_g_mydebugwindow = newScript()

format "% %\n" current_crowd the_frame_time to:_g_mydebugwindow

)

)

Notes

You can perform the following MAXScript operations

deleteitem <array> <itemnumber>

<array> = #(item,item...)

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.

<Crowd>.behaviors -- array of Behavior objects

<Crowd>.teams -- array of CrowdTeam objects

<Crowd>.assignments -- array of Assignment objects

<Crowd>.cogcontrols -- array of CognotiveController objects

<Crowd.scatter>.ObjectsToScatter -- node array

<Crowd.objAssoc>.objects -- node array

<Crowd.objAssoc>.delegates -- node array

<Crowd.smooth>.objects -- node array

If you delete a team or a cognitive controller via MAXScript deleteitem $crowd01.teams[1] 1 or deleteitem $crowd01.cogcontrols[1] 1, it may still be referenced by some assignments. Nothing will go wrong, but it's a strange thing to do and one probably should not do it.

The following MAXScript operations will cause Crowd to fail, either right away or later:

NEVER set a Crowd ArrayParameter element to undefined.

NEVER set a Crowd ArrayParameter element to to anything other than an object of the appropriate type.


CogControl : MAXObject

Constructor

CogControl ...

Properties

<cogcontrol>.name String Default: " CognitiveControl"

The name of the state diagram.

<cogcontrol>.startState CrowdState Default: Undefined

Set the starting CrowdState. By default the state that executes first in a cognitive controller is the one that was added first.

<cogcontrol>.states ArrayParameter Default: #() -- array of CrowdState objects

All of the states used by this cognitive controller.

Notes

You can perform the following MAXScript operations

deleteitem <array> <itemnumber>

<array> = #(item,item...)

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.

<CogControl>.states -- array of CrowdState objects

If you delete a CrowdState (deleteitem $crowd01.cogcontrols[1].states 1), it may still be referenced by either the startState or by a CrowdTransition stored in another CrowdState.

The following MAXScript operations will cause Crowd to fail, either right away or later:

NEVER set a States ArrayParameter element or the startState to undefined.

NEVER set a States ArrayParameter element or the startState to anything other than a CrowdState.

See also

CrowdState:MAXObject

CrowdAssignment : MAXObject

CrowdTeam : MAXObject

CogControl : MAXObject

Node Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Crowd Priority Properties

<Crowd.priority>.start Integer Default: 0

<Crowd.priority>.delegates ArrayParameter Default: #() -- node array

<Crowd.priority>.object Node Default: Undefined

<Crowd.priority>.grid Node Default: Undefined

<Crowd.priority>.increment Integer Default: 0

<Crowd.priority>.showPriorities Boolean Default: False

See also

Crowd : helper


Crowd Behaviors

Avoid_Behavior : MAXObject

Orientation_Behavior : MAXObject

Path_Follow_Behavior : MAXObject

Repel_Behavior : MAXObject

Scripted_Behavior : MAXObject

Seek_Behavior : MAXObject

Space_Warp_Behavior: MAXObject

Speed_Vary_Behavior : MAXObject

Surface_Arrive_Behavior : MAXObject

Surface_Follow_Behavior : MAXObject

Wall_Repel_Behavior : MAXObject

Wall_Seek_Behavior : MAXObject

Wander_Behavior : MAXObject


Avoid_Behavior : MAXObject

Constructor

Avoid_Behavior ...

AvoidBehavior ...

Properties

<Avoid_behavior>.name String Default: "Avoid"

<Avoid_behavior>.obstacles ArrayParameter Default: #() -- node array

Any object or objects that the delegates must keep away from.See Notes below.

<Avoid_Behavior>.lookAhead Integer Default: 30 -- animatable

The number of frames in advance of the current frame that the software looks for potential collisions.

<Avoid_behavior>.hardRadius Float Default: 1.0 -- animatable

Distance from center of the delegate(s), where no penetration should occur.

<Avoid_Behavior>.showHardRadius Boolean Default: False

Enables display of a wireframe sphere that depicts the extent of the .hardRadius setting.

<Avoid_Behavior>.detourAngle Float Default: 360.0 -- animatable

Maximum necessary turning angle relative to the direction of delegate's goal that the delegate will steer to avoid rather than slow down and wait.

<Avoid_Behavior>.brakePressure Float Default: 2.0 -- animatable

Determines how strongly the brakes are applied. Higher values induce more gradual and slower stops, but may cause brakes to "pump" in order to slow down.

<Avoid_behavior>.repelStrength Float Default: 0.2 -- animatable

Determines the strength of the repelling force; higher values result in greater repulsion force.

<Avoid_behavior>.repelRadius Float Default: 3.0

Distance from hard radius of delegate where "repel" avoidance is sensed and carried out.

<Avoid_behavior>.repelFalloff Float Default: 3.0 -- animatable

Higher values cause the repel to fall off to zero more rapidly with distance, thus focusing its effect closer to the delegate's hard radius.

<Avoid_behavior>.vfieldStrength Float Default: 1.0 Alias Vector_Field_Avoid_Strength -- animatable

Higher values result in more severe influence. Delegates will be directed to move perpendicular to the field.

<Avoid_behavior>.vfieldFalloff Float Default: 8.0 Alias Vector_Field_Falloff -- animatable

Higher values cause vector field influence to fall off to zero more rapidly with distance, thus focusing its effect closer to the delegate's hard radius.

<Avoid_Behavior>.showRepelRadius Boolean Default: False

When true, displays a wireframe sphere that depicts the extent of the .repelRadius setting.

<Avoid_Behavior>.showPotentialCols Boolean Default: False

When true, displays a green line from the delegate to the location of a potential collision.

<Avoid_Behavior>.showRepelActivity Boolean Default: False

When true, displays a white line between the delegate and target when the repel force is in effect.

<Avoid_Behavior>.showLookAhead Boolean Default: False

When true, displays a sphere that shows the current distance used to check for potential collisions.

<Avoid_behavior>.forceColor Color Default: (color 255 0 0)

Sets the color used to draw the Avoid force vector during the solution.

<Avoid_behavior>.displayForce Boolean Default: True

When true, force exerted on the delegate(s) by the Avoid behavior is drawn in the viewports as a vector during the simulation solution.

Notes

You can perform the following MAXScript operations

deleteitem <array> <itemnumber>

<array> = #(item,item...)

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.

<Avoid_Behavior>.obstacles

The following MAXScript operations will cause Crowd to fail, either right away or later:

NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Orientation_Behavior : MAXObject

Constructor

Orientation_Behavior ...

OrientationBehavior ...

Properties

<orientation_behavior>.name String Default: "Orientation"

<Orientation_Behavior>.headingRelative Boolean Default: False

<orientation_behavior>.minheading Float Default: -180.0 Alias: HeadingMin – animatable

The minimum permissible heading. This number should be lower than the Min Heading value. Range=-180 to 180.

<orientation_behavior>.maxheading Float Default: 180.0 –HeadingMax – animatable

The maximum permissible heading. This number should be higher than the Min Heading value. Range=-180 to 180.

<orientation_behavior>.maxHeadingVel Float Default: 180.0 Alias: maxHeadingVelocity – animatable

Specifies how much the delegate's heading can change per frame. This controls angular acceleration and deceleration.

<orientation_behavior>.headingresponse Float Default: 1.0 – animatable

Determines how quickly the heading follows the direction the object is moving in. A value of 1.0 indicates maximum responsiveness, and will point in the direction the delegate is moving while a lower value means that it is less responsive. Range=0 to 1.

<orientation_behavior>.minpitch Float Default: -180.0 Alias: PitchMin – animatable

The minimum number of degrees a delegate can incline or decline. This number should be lower than the Max Pitch value. Range=-180 to 180.

<orientation_behavior>.maxpitch Float Default: 180.0 Alias: PitchMax – animatable

The maximum number of degrees a delegate can incline or decline. This number should be higher than the Min Pitch value. Range=-180 to 180.

<orientation_behavior>.maxpitchVel Float Default: 1.0 Alias: maxPitchVelocity – animatable

Specifies how much the delegate's pitch can change per frame. This controls angular acceleration and deceleration.

<orientation_behavior>.pitchresponse Float Default: 1.0 – animatable

Determines how quickly the pitch follows the direction the object is moving in. A value of 1.0 indicates maximum responsiveness while a lower value means that it is less responsive. Range=0 to 1.

<orientation_behavior>.maxbank Float Default: 30.0 – animatable

The maximum number of degrees the delegate can bank.

<orientation_behavior>.maxbankAccel Float Default: 3.0 Alias: MaxBank_Change – animatable

The maximum number of degrees the delegate's bank angle can change per frame. This controls angular acceleration and deceleration.

<orientation_behavior>.bankPerTurn Float Default: 1.0 – animatable

The number of degrees the delegate will bank as a function of the turn angle at the current frame. For example, if Bank per Turn=1, the delegate will bank one degree for every degree it is turning at a given frame.

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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Path_Follow_Behavior : MAXObject

Constructor

Path_Follow_Behavior ...

PathFollowBehavior ...

Properties

<path_follow_behavior>.name String Default: "Path Follow"

<path_follow_behavior>.path Node Default: Undefined

A path object. Suitable path objects include splines and NURBS curves. If a path object contains more than one spline or curve, character studio uses the lowest-numbered element (usually the earliest created one).

<path_follow_behavior>.radius Float Default: 20.0 Alias: Radius_about_Path -- animatable

The radial distance from the path within which the delegate stays while traversing the path. Range=0.0 to 99,999.0.

<path_follow_behavior>.awareness Float Default: 0.5 -- animatable

Specifies how "intelligent" the delegate is while traversing this path. A high Awareness setting means that it takes into account the curve of the path while moving and will try to anticipate changes. A low value for Awareness, on the other hand, means that the delegate notices the path only when leaving it. Range=0.0 to 1.0.

Note: You can randomize awareness behavior with the Deviation and Seed settings.

<path_follow_behavior>.awareDeviation Float Default: 0.0 Alias: AwarenessDeviation -- animatable

Specifies the maximum amount by which Awareness should vary. character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the Awareness setting, and adds the result to Awareness. Range=0.0 to 1.0.

Note: You can vary behaviors among different Path Follow behaviors that use the same Awareness and Deviation settings by changing the Seed value.

<path_follow_behavior>.start Integer Default: 0 -- animatable

0 - Path Beginning

1 - Path End

This setting determines where on the path the delegate begins to follow the path.

<path_follow_behavior>.direction Integer Default: 0 -- animatable

0 – Forwards: The delegate moves along path vertices in ascending order.

1 – Backwards: The delegate moves along path vertices in descending order.

<path_follow_behavior>.endAction Integer Default: 0 -- animatable

0 – Loop: The delegate loops around the path, even if it isn't closed. If Beginning of Path or End of Path is chosen, it returns to the path's start or end point each time it finishes traversing the path. If Nearest Point is chosen, it returns to an arbitrary point determined by its position and the path shape.

1 – Reverse: The delegate reverses direction at the end of the path. Use this choice to simulate a back-and-forth "patrol" behavior.

2 – Continue: The delegate continues moving in the same direction it faced at the end of the path until the simulation ends or it's acted upon by another force or behavior.

<path_follow_behavior>.seed Integer Default: 1 -- animatable

Specifies a seed value for randomizing Awareness.

<path_follow_behavior>.forceColor Color Default: (color 0 0 255)

The color used to draw the Path Follow force vector during the solution.

<path_follow_behavior>.displayForce Boolean Default: True

When true, force exerted on the delegate(s) by the Path Follow behavior is drawn in the viewports as a vector during the simulation solution.

<path_follow_behavior>.targetColor Color Default: (color 0 0 127.5)

Sets the color used to draw the target icon.

<path_follow_behavior>.displayTarget Boolean Default: True

Enables display of the target icon, which appears during the solution when a new interim goal is calculated for the delegate.

<path_follow_behavior>.targetScale Float Default: 5.0 -- animatable

The overall size of the target icon.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Repel_Behavior : MAXObject

Constructor

Repel_Behavior ...

RepelBehavior ...

Properties

<Repel_Behavior>.name String Default: "Repel"

<Repel_Behavior>.repulsionSources ArrayParameter Default: #() -- node array

See Notes below

<Repel_Behavior>.targetComp Integer Default: 0

0-Closest Source : Each delegate is repelled by the closest of the assigned sources. Use this to have delegates assigned a single Repel behavior move away from sources in different directions.

1-Average of Sources : All delegates head to a common point determined by averaging all sources' locations.

<Repel_Behavior>.repelMethod Integer Default: 0 -- animatable

0-Angle : Applies a force to the delegate based on the angle between the delegate's current direction and the direction it would need to take in order to be moving directly away from the source. If the behavior's Weight is set to 1, the delegate will be given a force that points directly away from the source. If Weight is set to .5, the force will bisect the angle between its current direction and the direction opposite that of the source.

1-Force : Always applies a force directly away from the source, but at different magnitudes. If the behavior's Weight is 1, the magnitude of the force will be the average speed. If the Weight is .5, the magnitude of the force will be half the average speed.

<Repel_Behavior>.useRadii Boolean Default: True

When true, the behavior applies only to delegates closer to the target than the Outer Distance value.

<Repel_Behavior>.innerRadius Float Default: 0.0 -- animatable

The distance from the target at which the force is applied at full strength.

<Repel_Behavior>.outerRadius Float Default: 10.0 – animatable

The distance from the target at which the force begins to be applied.

<Repel_Behavior>.falloff Float Default: 2.0 -- animatable

<Repel_Behavior>.forceColor Color Default: (color 255 0 255)

The color used to draw the Repel force vector.

<Repel_Behavior>.showRadii Boolean Default: True

When true, the radii are displayed when the force is active.

<Repel_Behavior>.displayForce Boolean Default: True

When true, force exerted on the delegate(s) by the Repel behavior is drawn in the viewports as a vector during the simulation solution. If Use Radii is turned on, the radii are also displayed when the force is active.

Notes

You can perform the following MAXScript operations

deleteitem <array> <itemnumber>

<array> = #(item,item...)

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.

<Repel_Behavior>.repulsionSources

The following MAXScript operations will cause Crowd to fail, either right away or later:

NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Scripted_Behavior : MAXObject

Introduction to the Crowd System

The crowd system works by assembling all of the force vectors and speeds for a delegate from its active force behaviors. Then based upon the delegate's motion parameters, these force vectors 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.

Constructor

Scripted_Behavior ...

ScriptedBehavior ...

Properties

<scripted_behavior>.name String Default: "Scripted"

<Scripted_Behavior>.scriptContextName String Default: "apply" Alias: Script_Context_Name

The script functions declared in the Edit MaxScript window are declared in a hidden MaxScript context. This textbox specifies the name of the context. Giving a unique name here avoids conflicts between different scripted behaviors.

<Scripted_Behavior>.type Integer Default: 0 Alias: Behavior_Type

One of three behavior types: Force, Constraint, or Orientation.

Force: Behaviors of this type force the delegates to move in a particular direction, for example, Seek and Repel. Force behaviors work by returning a force vector 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

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

Scripted Behavior Syntax

The scripted behavior script is implemented by defining a set of event handlers that get called by the crowd system when solving the simulation. The event handlers are automatically enclosed into a hidden MAXScript context. The name of the context is taken from the dialog's Script Context Name text box or its equivalent .scriptContextName.

Event Handlers for Scripted Behaviors

on execute do <expr>

Called whenever the script is evaluated. All initializing should be done here.

on setupDelegates <delegates> <behavior> do <expr>

<delegates> an array of all the delegates after they are ordered participating in the simulation. All delegates listed in the Behavior Assignments pane of the Behavior and Team Assignment dialog are found in this list.

<behavior> the current behavior

Called before the simulation starts.

Note

All of the delegates are passed in, regardless if they have this behavior assigned, so the behavior knows the max number of delegates that may be used and therefore set up whatever data structures required. Some behaviors need to keep track of parameters on a per delegate basis. This function allows the behavior to set up data structures to get that info. Also that is one of the reasons why the delegate.id is unique, so it can be used to hash or index these data structures. Due to cognitive controllers, you never really know exactly all of the delegates which will be active for a particular behavior.

on display <behavior> <time> do <expr>

<behavior> the current behavior

<time> current time of the simulation

Called every time the crowd system is redrawn. You can use the low level drawing functions from the gw struct, Viewport Drawing Methods, to have a custom display for the behaviors.

Note

This handler gets called a number of times, so the system will slow down if implemented.

on behaviorStarted <delegate> <behavior> <time> do <expr>

<delegate> the delegate node the behavior is assigned to

<behavior> the current behavior

<time> current time of the simulation

Called whenever a behavior becomes active for a particular delegate. This can occur at the beginning of the simulation for an assigned behavior or when a cognitive controller activates the behavior.

on initAtThisTime <behavior> <time>

This function is called for each behavior at the beginning of the frame.

on applyForce <delegate> <behavior> <time> <numSubSamples> <displayHelpers> <weight> do <expr>

If the behavior type is Force or Orientation, this handler is called every frame to move the delegate.

<delegate> the delegate node the behavior is assigned to

<behavior> the current behavior

<time> current time of the simulation

<numSubSamples> is the number of sub samples required per frame.

<displayHelpers> this value is true/false depending on the <Crowd>.update and <Crowd>.updateFrequency, as well as the current frame. If it is true, you should display any helper imagery you want using the display functions available from the delegates structure. For instance, most behaviors display their force if this is true, and pathfollow also displays its target. The delegates.lineDisplay ,.sphereDisplay , .bboxDisplay , and .textDisplay are all functions which can be used to draw a graphic primitive for a particular delegate when the crowd simulation is being solved. Please see Viewport Drawing Methods for additional viewport drawing methods.

Note

The graphic window functions gw.* described in Viewport Drawing Methods will not display correctly or at all while in Step Solve.

<weight> this behavior's weight on the delegate

The event handler should return an array of the following type:

#(<int_flags>, <point3_force>, <point3_goal>, <float_speed>, <Speed_Weight_at_the_Goal>)

<int_flags> sum of any of the following values:

0 – the return value is not used by the crowd system

1 - only force is affected

2 - only goal is affected

4 - only speed is affected

For example, a value of 5, (1+4), indicates that the force and speed are affected.

<point3_force> the force vector. 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.

<float_speed> the net speed of the delegate. This value should be normalized to the average speed of the delegate. A value of 1.0 means go at the average speed.

<Speed_Weight_at_the_Goal> will represent the
speed that the delegate should be at when it reaches
its goal. This value should be normalized by the average speed of the delegate, so that a value of 1.0 equal it's average speed.

Notes

Any behavior that sets the <int_flags> with a speed affected setting should ensure that a valid value is set for <float_speed> and <Speed_Weight_at_the_Goal>. Note that a goal doesn't need to be set
for this to work. This is how the 'SpeedVary' behavior works with Biped. It doesn't explicitly set a goal but still modifies the <Speed_Weight_at_the_Goal> value.

on constraint <delegate> <behavior> <time> <numSubSamples> <displayHelpers> <finalSet> <velocity> <speed> <pos> do <expr>

If the behavior type, <Scripted_Behavior>.type, is Constraint, this handler is called at least once every frame to constrain the delegate. The constraint behavior will override any other force behavior, the Avoidance Behavior, plus it will override any acceleration limits, speed limits etc. So it should be used with caution in a simulation.

The constraint behavior constrains the position that the delegate is moving towards by changing the current position that the delegate is already at, it's current velocity, and it's current speed. These values are combined to get the next position, Next_position = Current_Position +Normalized(vel) * Speed. Changing the current position doesn't actually change where it is at though, it just changes the position that is used to calculate it's new position. This design allows the constraint to make the objects velocity change abruptly and keep its speed, thus conserving the energy of the delegate.

<delegate> the delegate node the behavior is assigned to

<behavior> the current behavior

<time> current time of the simulation

<numSubSamples> is the number of sub samples required per frame.

<displayHelpers> this value is true/false depending on the <Crowd>.update and <Crowd>.updateFrequency, as well as the current frame. If it is true, you should display any helper imagery you want using the display functions available from the delegate. For instance, most behaviors display their force if this is true, and pathfollow also displays its target. The delegates .lineDisplay, .sphereDisplay, .bboxDisplay, and .textDisplay are all functions which can be used to draw a graphic primitive for a particular delegate when the crowd simulation is being solved. Please see Viewport Drawing Methods for additional viewport drawing methods.

<finalSet> whether or not this is the final time this behavior will be called during the current frame.

Note

In order to handle constraints working correctly within the avoidance system the constraint behavior may be called more than once per frame. When the passed in parameter, finalSet, is true, it will be the last time the constraint function is called for that frame.

Currently the constraint behavior's "on constraint" event handler is called twice per frame. The first call occurs before an existing Avoid_Behavior with the passed in parameter finalSet having a value of false. The second call occurs, after the delegate's limits and Avoid_Behavior are applied with the passed in parameter finalSet having a value of true. This evaluation order is done so that the delegate's limits and the Avoid_Behavior can affect the changes that the constraint performs. The second call is made to make sure that the constraint is still being met.

One reason to check the state of finalSet is if internally something was cached and you didn't want it to change. For example, the Surface_Follow constraint behavior keeps track of which triangle it's on and the barycentric coordinates of where it's at. The simulation will not change these values until finalSet is true.

<velocity> the current velocity of the delegate at this frame.

<speed> the current speed of the delegate at this frame.

<pos> the current position of the delegate at this frame.

Note

After the last delegate's "on constraint" has executed for the last frame of the simulation, "on setupDelegates delegates behavior do" will be called with an empty array "#() ReferenceTarget:Scripted_Behavior". This is guarenteed and can be used by written constraint behaviors to clear out any internal caches.

The event handler should return an array of the following type:

#(<int_flags>, <point3_velocity>, <point3_pos>, <point3_goal>, <float_speed>)

<int_flags> sum of any of the following values:

0 – the return value is not used by the crowd system

1 – the return value is used by the crowd system

<point3_velocity> the velocity.

<point3_pos> the modified current position that is used to calculate it's new position. In order to meet a constraint this behavior is allowed to modify the current position of a delegate.

<point3_goal> the goal position in world space.

<float_speed> the net speed of the delegate. This value should be normalized to the average speed of the delegate.

on orient <delegate> <behavior> <time> <velocity> do <expr>

If the behavior type, <Scripted_Behavior>.type, is Orientation, this handler is called every frame. This handler is always called in conjunction with the applyForce handler.

<delegate> the delegate node the behavior is assigned to

<behavior> the current behavior

<time> current time of the simulation

<velocity> the current velocity of the delegate at this frame.

The event handler should return an array of the following type:

#(<int_flags>, quat_orientation)

<int_flags> sum of any of the following values:

0 – the return value is not used by the crowd system

1 – the return value is used by the crowd system

<quat_orientation> the orientation of the delegate in quaternions.

Notes

The purpose of passing the crowd delegate and behavior to all of the event handlers is that you can call persisted global, saved with scene, MAXScript functions that work for more than one crowd simulation.

Example

The following is a pair of scripted behaviors called "FormationConstraint" and "FormationOrientation".

The "FormationOrientation" will constrain the orientation to a fixed location, in this case based on the current delegate's orientation found at its first rotation keyframe. The entire scripted orientation behavior can be implemented with one event handler:

on orient delegate behavior time vel do

(

#(1,delegate.rotation.keys[1].value as quat )

)

The "FormationConstraint" keeps a team of delegates in a given positional formation while maintaining the pace and direction of a designated leader named "FormationLeader". This is similar to a drum major and a marching band or like football blockers running in front of a running back who may dart in any direction. This person dictates how and where the formation will move. This "FormationLeader" is not using the scripted behavior.

This behavior will affect both the position and orientation of the delegate. The orientation is being calculated by the delegate's velocity, and the velocity is being set correctly.

on execute do ( print " executed" )

on constraint delegate behavior time numsubsamples displayHelpers finalSet vel speed pos do

(

leader_velocity = delegates.velocity $TheFormationLeader

Normalized_Leader_Velocity = normalize (delegates.velocity $TheFormationLeader)

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

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods value_common_properties_operators_and_methods


Seek_Behavior : MAXObject

Constructor

Seek_Behavior ...

SeekBehavior ...

Properties

<seek_behavior>.name String Default: "Seek"

<seek_behavior>.targets ArrayParameter Default: #() -- node array

See Notes below.

Specify the object or objects as a stationary or moving target for delegates. Delegates move toward the target during the crowd simulation while turning as necessary.

<seek_behavior>.targetComp Integer Default: 0

0 - Closest Source Only: Each delegate seeks the closest of the assigned targets. Use this to have delegates assigned a single Seek behavior move in different directions.

1 - Average of Sources: All delegates head to a common point determined by averaging all targets' locations.

<seek_behavior>.seekMethod Integer Default: 0 -- animatable

0 – Angle: Applies a force to the delegate based on the angle between the delegate's current direction and the direction it would need to take in order to be moving directly towards the goal. If the Weight of the Seek behavior is 1, the delegate will be given a force that points directly towards the goal. If it's .5 it will bisect the angle between its current direction and the direction of the goal.

1 – Force: Applies a force in the direction of the goal always, but at different magnitudes. If the Weight of the Seek behavior is 1, the magnitude of the force will be the average speed. If the Weight of the Seek behavior is .5, the magnitude of the force will be half the average speed.

<seek_behavior>.forceColor Color Default: (color 0 255 0)

The color used to draw the Seek force vector during the solution.

<seek_behavior>.displayForce Boolean Default: True

When true, force exerted on the delegate(s) by the Seek behavior is drawn in the viewports as a vector during the simulation solution.

<Seek_Behavior>.useRadii Boolean Default: False

When true, the Seek behavior applies only to delegates less than the Outer Radius distance from the target.

<Seek_Behavior>.showRadii Boolean Default: True

When true, the radii are displayed when the force is active.

<Seek_Behavior>.innerRadius Float Default: 0.0 -- animatable

The distance from the target at which Seek is applied at full strength.

<Seek_Behavior>.outerRadius Float Default: 10.0 -- animatable

The distance from the target at which Seek begins to be applied.

<Seek_Behavior>.falloff Float Default: 2.0 -- animatable

Notes

You can perform the following MAXScript operations

deleteitem <array> <itemnumber>

<array> = #(item,item...)

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.

<Seek_Behavior>.targets

The following MAXScript operations will cause Crowd to fail, either right away or later:

NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Space_Warp_Behavior: MAXObject

Constructor

Space_Warp_Behavior ...

WSMBehavior ...

Properties

<space_warp_behavior>.name String Default: "Space Warp"

<space_warp_behavior>.spaceWarp Node Default: Undefined

<space_warp_behavior>.forceColor Color Default: (color 255 255 0)

The color used to draw the Space Warp force vector during the solution.

<space_warp_behavior>.displayForce Boolean Default: True

When true, force exerted on the delegate(s) by the Space Warp behavior is drawn in the viewports as a vector during the simulation solution.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Speed_Vary_Behavior : MAXObject

Constructor

Speed_Vary_Behavior ...

SpeedVaryBehavior ...

Properties

<speed_vary_behavior>.name String Default: "Speed Vary"

<speed_vary_behavior>.period Integer Default: 10 -- animatable

Specifies how many frames should elapse before a new speed is chosen.

<speed_vary_behavior>.period_deviation Float Default: 0.5 -- animatable; Alias: Period_Deviation

Specifies the maximum amount by which Period should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the Period setting, and adds the result to Period. Range=0.0 to 1.0.

<speed_vary_behavior>.center_speed Float Default: 1.0 -- animatable; Alias: Center_Speed

Specifies the speed the delegate should change to. Center is a multiplier: A value of 0.0 means to stop, a value of 1.0 means to move at its average speed, and a value greater than 1.0 means to move faster than its average speed. Range=0.0 to 99,999.0.

<speed_vary_behavior>.speed_deviation Float Default: 0.25 -- animatable; Alias: Speed_Deviation

Specifies the maximum amount by which the delegate's calculated speed (Average Speed*Center) should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the calculated speed, and adds the result to the calculated speed. Range=0.0 to 99,999.0.

<speed_vary_behavior>.seed Integer Default: 1 -- animatable; Alias: Speed_Vary_Seed

Specifies a seed value for randomizing the Wander behavior.

<speed_vary_behavior>.accelPeriod Float Default: 0.5 -- animatable; Alias: Acceleration_Period

Specifies the rate at which the delegate's speed should change. An acceleration of 1.0 means that the transition to the new speed will proceed as quickly as possible to its new speed, while a value of 0.0 means the transition will take the entire period. Range=0.0 to 1.0.

<speed_vary_behavior>.accelDeviation Float Default: 0.5 -- animatable; Alias: Acceleration_Deviation

Specifies the maximum amount by which the delegate's calculated speed (Average Speed*Center) should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the calculated speed, and adds the result to the calculated speed. Range=0.0 to 99,999.0.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Surface_Arrive_Behavior : MAXObject

Constructor

Surface_Arrive_Behavior ...

SurfaceArriveBehavior ...

Properties

<Surface_Arrive_Behavior>.name String Default: "Surface Arrive"

<Surface_Arrive_Behavior>.surfaces ArrayParameter Default: #() -- node array

See Notes below

<Surface_Arrive_Behavior>.disableAfterArriving Boolean Default: True

When true, turns off the Surface Arrive behavior after the delegate arrives at the surface.

<Surface_Arrive_Behavior>.rate Float Default: 0.5 -- animatable

A multiple of the delegate's Max Accel setting that specifies the acceleration with which it will try to arrive. A value of 1.0 uses the full acceleration of the delegate.

<Surface_Arrive_Behavior>.rateDeviation Float Default: 0.0 -- animatable

Adds a variation to the to the rate setting.

<Surface_Arrive_Behavior>.speed Float Default: 0.0 -- animatable

The speed at which to arrive and relative to the speed of the target.

<Surface_Arrive_Behavior>.speedDeviation Float Default: 0.0 -- animatable

Adds a variation to the to the speed setting.

<Surface_Arrive_Behavior>.distance Float Default: 1e+008 -- animatable

The maximum radial distance from the target within which the behavior will be active. Until the delegate is within this radius, the behavior will have no influence.

<Surface_Arrive_Behavior>.distanceDeviation Float Default: 0.0 -- animatable

Adds a variation to the to the distance setting.

<Surface_Arrive_Behavior>.offset Float Default: 0.0 -- animatable

Specifies a consistent distance from the calculated arrival point, based on the surface normal, for the delegate to use.

<Surface_Arrive_Behavior>.facing Boolean Default: False -- animatable

When true, the delegate will try to arrive only at points on triangles on the surface that are facing it.

<Surface_Arrive_Behavior>.random_closest Integer Default: 0

0 – Random: The software chooses a random point on the target surface as the arrival point.

1 – Closest: The software chooses the closest point on the target surface as the arrival point.

<Surface_Arrive_Behavior>.everyFrame Boolean Default: False -- animatable

When true, the software chooses arrival points for delegates at every frame. Available only when Closest is chosen.

<Surface_Arrive_Behavior>.displayOffset Boolean Default: False

When true, shows the Offset distance as lines emanating from each vertex in the surface object, perpendicular to the surface.

<Surface_Arrive_Behavior>.height Float Default: 0.0 -- animatable

Specifies a distance from the arrival point along its face normal. This is the point that the delegate will go to first before descending to the arrival point.

<Surface_Arrive_Behavior>.heightDeviation Float Default: 0.0 -- animatable

Adds random variation to the to the Height setting. See introduction for the formula used to calculate the deviation.

<Surface_Arrive_Behavior>.descentStart Float Default: 0.0 -- animatable

Specifies the distance between the delegate and the arrival point at which the descent should start.

Note

Be careful that Descent Start is set high enough that the delegate won't overshoot when descending because its speed is too high and deceleration too low, compared to when it should start descending.

<Surface_Arrive_Behavior>.descentstartDeviation Float Default: 0.0 -- animatable

Adds a variation to the to the Descent Start setting.

<Surface_Arrive_Behavior>.useNormal Boolean Default: False Alias: Off_This_Normal

When true, use vector specified in the .xNormal, .yNormal, and .zNormal to specify the angle at which the final approach occurs.

<Surface_Arrive_Behavior>.xNormal Float Default: 0.0 -- animatable; Alias: X_Normal

Specify the final approach X value for the vector in world coordinates.

<Surface_Arrive_Behavior>.yNormal Float Default: 0.0 -- animatable; Alias: Y_Normal

Specify the final approach Y value for the vector in world coordinates.

<Surface_Arrive_Behavior>.zNormal Float Default: 1.0 -- animatable; Alias: Z_Normal

Specify the final approach Z value for the vector in world coordinates.

<Surface_Arrive_Behavior>.seed Integer Default: 1 -- animatable

Affects the random numbers used to calculate the Deviation settings.

<Surface_Arrive_Behavior>.targetColor Color Default: (color 0 0 127.5)

The color used to draw the target icon.

<Surface_Arrive_Behavior>.displayTarget Boolean Default: True

When true, displays the target icon which appears during the solution when a new interim goal is calculated for the delegate.

<Surface_Arrive_Behavior>.targetScale Float Default: 5.0 -- animatable

Specifies the overall size of the target icon.

Methods

SurfaceArriveBhvr.Getstate <Surface_Arrive_Behavior> <delegate_node>

Returns an integer value giving the state the delegate is in with respect to the Surface_Arrive_Behavior. A return value of -1 means that the delegate isn't active for that state, 0 means that the delegate is outside the distance radius and so isn't arriving, 1 means that the delegate is in the process of arriving, and 2 means that the delegate has arrived. If 'Disable After Arriving' is TRUE, the delegates will never reach state 2.

The main purpose of this funtion is so that the 'State' of a delegate as it arrives to a surface can be determined from MAXScript. It can be used for both the cognitive controller transitions as well as the script definable in MotionClips. See the ClipState Dialog and the Cognitive Controller topics in the character studio 3 online reference for more details.

Track View > Global Tracks > Block Control > GlobalClip Properties > Synthesis dialog > State Tab > New State > Edit Properties > ClipState dialog

Select a Crowd helper. > Modify panel > Global Clip Controllers rollout > New > Choose GlobalClip object. > Select object in list. > Edit > Synthesis dialog > State Tab > New State > Edit Properties > Clip State dialog

Create panel > Helpers > Object Type rollout > Crowd > Setup rollout > Cognitive Controllers

Select a Crowd object. > Modify panel > Setup rollout > Cognitive Controllers

SurfaceArriveBhvr.getPos <Surface_Arrive_Behavior> <delegate_node>

Returns a Point3 value of the position that the delegate is arriving to at the time the function is called.

Notes

You can perform the following MAXScript operations

deleteitem <array> <itemnumber>

<array> = #(item,item...)

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.

<Surface_Arrive_Behavior>.surfaces

The following MAXScript operations will cause Crowd to fail, either right away or later:

NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Surface_Follow_Behavior : MAXObject

Constructor

Surface_Follow_Behavior ...

SurfaceFollowBehavior ...

Properties

<Surface_Follow_Behavior>.name String Default: "Surface Follow"

<Surface_Follow_Behavior>.surfaces ArrayParameter Default: #() -- node array

See Notes below.

<Surface_Follow_Behavior>.useProjection Bolean Default: False

When true, Surface Follow calculates delegate direction from the specified vector, rather than using the default.

<Surface_Follow_Behavior>.xVector Float Default: 0.0 -- animatable

Specifies the x component of a vector using world coordinates. . Range=-1.0 to 1.0.

<Surface_Follow_Behavior>.yVector Float Default: 0.0 -- animatable

Specifies the y component of a vector using world coordinates. . Range=-1.0 to 1.0.

<Surface_Follow_Behavior>.zVector Float Default: 1.0 -- animatable

Specifies the z component of a vector using world coordinates. . Range=-1.0 to 1.0.

<space_warp_behavior>.targetColor Color Default: (color 0 0 127.5)

Sets the color used to draw the Surface Follow during the solution.

<space_warp_behavior>.displayTarget Boolean Default: True

When true, the interim goal for each delegate influenced by the Surface Follow behavior is drawn in the viewports as a wireframe sphere during the simulation solution.

Notes

If the delegate starts out away from the surface to be followed then the target is most visible before the delegate reaches the surface where the target is positioned along the surface edge.

While the delegate is actually following the surface, the target is usually coincident with the delegate because Surface follow sets a new destination only a frame or two ahead.

<space_warp_behavior>.targetScale Float Default: 5.0

Specifies the overall size of the target icon.

<Surface_Follow_Behavior>.offset Float Default: 0.0 -- animatable

Specifies the delegate's distance above the surface, using the surface normal.

<Surface_Follow_Behavior>.displayOffset Boolean Default: False

When true, shows the .offset distance as lines emanating from each vertex in the surface object, perpendicular to the surface.

Notes

You can perform the following MAXScript operations

deleteitem <array> <itemnumber>

<array> = #(item,item...)

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.

<Surface_Follow_Behavior>.surfaces

The following MAXScript operations will cause Crowd to fail, either right away or later:

NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Wall_Repel_Behavior : MAXObject

Constructor

Wall_Repel_Behavior ...

WallRepelBehavior ...

Properties

<Wall_Repel_Behavior>.name String Default: "Wall Repel"

<Wall_Repel_Behavior>.repelGrids ArrayParameter Default: #() -- node array

Set the repelling grid.

<Wall_Repel_Behavior>.repelMethod Integer Default: 0 -- animatable

Determines whether delegate direction as influenced by the behavior is calculated by an angular method or a force method.

0 – Angle: Applies a force to the delegate based on the angle between the delegate's current direction and the direction it would need to take in order to be moving directly away from the source. If the behavior's Weight is set to 1 the delegate will be given a force that points directly away from the source. If Weight is set to .5, the force will bisect the angle between its current direction and the direction opposite that of the source.

1 – Force: : Always applies a force directly away from the source, but at different magnitudes. If the behavior's Weight is 1, the magnitude of the force will be the average speed. If the Weight is .5, the magnitude of the force will be half the average speed.

<Wall_Repel_Behavior>.repelDirection Integer Default: 0 -- animatable

Determines whether the grid repels from its positive-axis side, its negative-axis side, or both.

0 – Positive Axis: The grid repels only from the positive-axis side.

1 – Negative Axis: The grid repels only from the negative-axis side.

2 – Both Axes: The grid repels from both sides.

<Wall_Repel_Behavior>.useDistance Boolean Default: True

When true, the behavior applies only to delegates closer to the target than the outerRadius value.

<Wall_Repel_Behavior>.innerDistance Float Default: 0.0 -- animatable

The distance from the target at which the force is applied at full strength.

<Wall_Repel_Behavior>.outerDistance Float Default: 10.0 -- animatable

The distance from the target at which the force begins to be applied.

<Wall_Repel_Behavior>.falloff Float Default: 2.0 -- animatable

<Wall_Repel_Behavior>.showDistance Boolean Default: True

Shows the inner and outer distance settings as grids offset from the target grid in the viewports. The .innerDistance grid is light blue, while .outerDistance grid is blue-white.

<Wall_Repel_Behavior>.gridSpacing Integer Default: 500

Specifies the spacing of grid lines used to draw the Inner/Outer Distance grids. The lower the value, the closer the spacing.

<Wall_Repel_Behavior>.gridEnd Boolean Default: True Alias: End_force_at_grid_edges

When true, the force emanates only from the grid object. When off, the force emanates from an imaginary infinite grid created by extending the grid plane in all directions.

<Wall_Repel_Behavior>.forceColor Color Default: (color 255 0 255)

Sets the color used to draw the Wall Repel force during the solution.

<Wall_Repel_Behavior>.displayForce Boolean Default: True

The force, when activated, is drawn in the viewports as a wireframe rectangle during the simulation solution.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Wall_Seek_Behavior : MAXObject

Constructor

Wall_Seek_Behavior ...

WallSeekBehavior ...

Properties

<Wall_Seek_Behavior>.name String Default: "Wall Seek"

<Wall_Seek_Behavior>.seekGrids ArrayParameter Default: #() -- node array

Set the repelling grid.

<Wall_Seek_Behavior>.seekMethod Integer Default: 0 -- animatable

Determines whether delegate direction as influenced by the behavior is calculated by an angular method or a force method.

0 – Angle: Applies a force to the delegate based on the angle between the delegate's current direction and the direction it would need to take in order to be moving directly toward the target. If the behavior's Weight is set to 1, the delegate will be given a force that points directly away from the target. If Weight is set to .5, the force will bisect the angle between its current direction and the direction opposite that of the target.

1 – Force: Always applies a force directly toward the target. If the behavior's Weight is 1, the magnitude of the force will be the average speed. If the Weight is .5, the magnitude of the force will be half the average speed.

<Wall_Seek_Behavior>.seekDirection Integer Default: 0 -- animatable

Determines whether the grid attracts from its positive-axis side, its negative-axis side, or both.

0 – Positive Axis: The grid attracts only from the positive-axis side.

1 – Negative Axis: The grid attracts only from the negative-axis side.

2 – Both Axes: The grid attracts from both sides.

<Wall_Seek_Behavior>.useDistance Boolean Default: True

When true, the behavior applies only to delegates closer to the target than the Outer Distance value.

<Wall_Seek_Behavior>.innerDistance Float Default: 0.0 -- animatable

The distance from the target at which the force is applied at full strength.

<Wall_Seek_Behavior>.outerDistance Float Default: 10.0 -- animatable

The distance from the target at which the force begins to be applied.

<Wall_Seek_Behavior>.falloff Float Default: 2.0 -- animatable

<Wall_Seek_Behavior>.showDistance Boolean Default: True

<Wall_Seek_Behavior>.gridSpacing Integer Default: 500

<Wall_Seek_Behavior>.gridEnd Boolean Default: True Alias: End_force_at_grid_edges

When true, the force emanates only from the grid object. When off, the force emanates from an imaginary infinite grid created by extending the grid plane in all directions.

<Wall_Seek_Behavior>.forceColor Color Default: (color 255 0 255)

Sets the color used to draw the Seek force vector during the solution.

<Wall_Seek_Behavior>.displayForce Boolean Default: True

When true, force exerted on the delegate(s) by the Seek behavior is drawn in the viewports as a vector during the simulation solution. If useRadii is turned on, the radii are also displayed when the force is active.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


Wander_Behavior : MAXObject

Constructor

Wander_Behavior ...

WanderBehavior ...

Properties

<wander_behavior>.name String Default: "Wander"

<wander_behavior>.period Integer Default: 10 -- animatable; Alias: Wander_Period

Specifies how many frames should elapse before a new direction is chosen.

<wander_behavior>.periodDeviation Float Default: 0.5 -- animatable; Alias: Wander_Period_Deviation

Specifies the maximum amount by which Period should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the Period setting, and adds the result to Period. Range=0.0 to 1.0.

<wander_behavior>.turnAngle Float Default: 0.5 -- animatable

Specifies how far to turn when changing direction. A small value means to change direction only by a small amount, while as the value approaches 1.0 it will randomly turn in any direction. Range=0.5 to 1.0.

<wander_behavior>.turnPeriod Float Default: 0.5 -- animatable

Specifies how long over the current period it takes to turn. A value of 0.0 means that it will rotate as quickly as possible to face a direction and then travel in that a direction, while a value of 1.0 means it will take the entire period to rotate in that direction. Range=0.5 to 1.0.

<wander_behavior>.turnPeriodDeviation Float Default: 0.5 -- animatable

Specifies the maximum amount by which Angle should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the Angle setting, and adds the result to Angle. Range=0.0 to 1.0.

<wander_behavior>.seed Integer Default: 1 -- animatable

Specifies a seed value for randomizing the Wander behavior.

<wander_behavior>.forceColor Color Default: (color 0 255 255)

The color used to draw the Wander force vector during the solution.

<wander_behavior>.displayForce Boolean Default: True

When true, force exerted on the delegate(s) by the Wander behavior is drawn in the viewports as a vector during the simulation solution.

See also

Crowd : Helper

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


MotionClips and GlobalMotionClip

globalMotionClipOps const StructDef Struct: globalMotionClipOps(

globalMotionClipOps.loadfile Primitive loadfile()

'loadfile' expects a GlobalMotionClip, then a filename for a "*.ant" GlobalMotionClip file to load.

globalMotionClipOps.savefile Primitive savefile()

'savefile' expects a GlobalMotionClip, then a filename for the "*.ant" file to save.

globalMotionClipOps.synthesize Primitive synthesize()

'synthesize' expects a GlobalMotionClip and will synthesize it.

Note that the GlobalMotionClip objects are found under the GlobalTracks.Block_Control list controller.

So to call savefile, one would call:

GlobalMotionClipOps.savefile GlobalTracks.Block_Control.globalMotionClip__globalObject "globalObject.ant"'

The following classes exist but are not supported.

MotionClipSlaveRotation : RotationController {4306d06,97c6025}

MotionClip : FloatController {e937ded,5a002ad2}

MotionClipSlavePos : PositionController {18c22740,522802b9}

ClipAssignerReferenceTarget : ReferenceTarget {2cb93ce2,33825f4}

MotionClipSlaveFloat : FloatController {31822cdf,34c146b}

Global_MotionClip : MasterBlockController {37d25755,278c6957}

ClipState : ReferenceTarget {455d5a81,3dcb1dc2}

ClipAssigner : ReferenceTarget {49f14ffa,33801afd}

MasterMotionClip : MasterBlockController {532a2038,6acd39bf}

MotionClipSlave_Point3 : Point3Controller {6c95514a,801b4f}

MotionClipSlaveScale : ScaleController {71031345,770b4347}

MotionClipFloatController : FloatController {7f016988,1f9f0342}


Vector_Field: SpacewarpObject

Constructor

Vector_Field ...

VectorField ...

Properties

<Vector_Field>.Length Float Default: 0.0 -- world units

Specify the length dimension of the vector field lattice. The lattice should be larger than the vector field object.

<Vector_Field>.Width Float Default: 0.0 -- world units

Specify the width dimension of the vector field lattice. The lattice should be larger than the vector field object.

<Vector_Field>.Height Float Default: 0.0 -- world units

Specify the height dimension of the vector field lattice. The lattice should be larger than the vector field object.

<Vector_Field>.LenSegs Integer Default: 1 Alias: Length_Segments

Specify the resolution of the vector field lattice's length segments. The greater the resolution, the higher the accuracy of the simulation.

<Vector_Field>.WidSegs Integer Default: 1 Alias: Width_Segments

Specify the resolution of the vector field lattice's width segments. The greater the resolution, the higher the accuracy of the simulation.

<Vector_Field>.HgtSegs Integer Default: 1 Alias: Height_Segments

Specify the resolution of the vector field lattice's height segments. The greater the resolution, the higher the accuracy of the simulation.

<Vector_Field>.showLattice Boolean Default: True

Set on to display the vector field lattice as a yellow wireframe box. The vectors are generated at lattice intersections inside the vector field range.

<Vector_Field>.showRange Boolean Default: True

Set on to display the volume about the obstacle object within which vectors are generated as an olive-colored wireframe.

<Vector_Field>.showVectors Boolean Default: False

Set on to display vectors, which appear as blue lines emanating outward from the lattice intersections within the range volume.

<Vector_Field>.showSurfSamps Boolean Default: False

Set on to display short green lines emanating from sample points on the surface of the obstacle object.

<Vector_Field>.vecScale Float Default: 1.0 -- world units

Scales the vectors so they're more visible or less obtrusive. This setting does not affect the strength of the vectors only their visibility.

<Vector_Field>.iconSize Float Default: 0.0 -- world units

Adjusts the size of the Vector Field space warp icon. The icon is a pair of crossed double-headed arrows. Increase the size for easier viewport selection.

<Vector_Field>.strength Float Default: 1.0 -- animatable; world units

Sets the degree of effect the vectors have on the movement of an object entering the vector field. Changing Strength does not require that you recalculate the vector field.

<Vector_Field>.falloff Float Default: 2.0 -- animatable; world units

Determines the rate at which the strength of the vectors falls off with distance from the surface of the object. A value of 0 will make all the vectors the same size. A value greater than 0 will make them get smaller as they get further away. A value less then 0 will make them get larger as they get further away.

<Vector_Field>.direction Integer Default: 1 -- animatable

Sets whether the force generated by the vectors works parallel or perpendicular to the vector field. Because the vectors are perpendicular to the object surface, and you typically would want delegates to travel parallel to the surface, you would normally use a perpendicular force.

0 – Parallel

1 - Perpendicular

<Vector_Field>.pull Float Default: 0.0 -- animatable; world units

Adjusts objects' position relative to the field. Available only when Perpendicular is chosen. Range=-1.0 to 1.0. Objects moving perpendicular to a vector field sometimes tend to drift away from it, due to lack of subsampling. The Pull parameter helps to pull objects back. Pull values greater than 0 create a pulling force towards the source of the vector field vector. Values less than 0 pull the force towards the direction in which the vector field's vector is pointing. A value of 0.0 produces a force perfectly perpendicular to the vector field's vector.

<Vector_Field>.object Node Default: Undefined Alias: Vector_Field_Object

The obstacle object around which the vector field is to be generated. Only primitives and unmodified editable mesh objects can be used as obstacles. The object should be fully enclosed in the Vector Field lattice.

<Vector_Field>.range Float Default: 1.0 -- world units

Determines the volume within which vectors are generated. The Range is represented in viewports as an olive-colored wireframe that starts out the same size and shape as the obstacle object. Increasing the Range setting moves the wireframe away from the obstacle object in the direction of its surface normals.

Notes

In crowd simulations, the Range outline is where the delegates start to "see" the obstacle object, and begin to turn to avoid it. If your crowd members are penetrating the obstacle, or even just coming too close to it before turning, increase the Range setting. Also try increasing the Vector Field lattice resolution and/or the Sample Res setting.

<Vector_Field>.resolution Integer Default: 1

Acts as a multiplier of the effective sampling rate used on the obstacle object's surface to calculate vector directions in the field. The basic sampling rate is determined by the program from the size of the lattice and the size of each polygon.

<Vector_Field>.flipFaces Boolean Default: False

Setting to true causes flipped normals to be used during the computation of the vector field. By default, vectors are generated in the same direction as the obstacle object's face normals, so that assuming its face normals point outward, objects move around its exterior in a crowd simulation. However, if you want objects to remain within an object's interior, turn on flipFaces.

<Vector_Field>.blendStart Float Default: 0.0 -- world units

The distance from the object at which blending the vectors starts.

<Vector_Field>.blendFalloff Float Default: 2.0 -- world units

The falloff of the blend of the surrounding vectors.

<Vector_Field>.blendWidSegs Integer Default: 1

The number of adjacent lattice points to blend on the X axis.

<Vector_Field>.blendLenSegs Integer Default: 1

The number of adjacent lattice points to blend on the Y axis.

<Vector_Field>.blendHgtSegs Integer Default: 1

The number of adjacent lattice points to blend on the Z axis.

Methods

vfields.computeVectors <Vector_Field>

Calculates the vector field using the current Vector Field parameters. Always recalculate the vector field after changing any of the non-display related parameters.

vfields.BlendVectors <Vector_Field>

Blends the vectors for reducing abrupt changes in angles of neighboring vectors.

Associated Methods

bindSpaceWarp <node> <Vector_Field_node>

Associated Binding Modifier

Vector_Field_Mod

This modifier is automatically created by the bindSpaceWarp() 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

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods


MAXScript and gmax

MAXScript is the built-in scripting language for gmax™. Because the functionality of MAXScript in gmax is almost identical to the latest version of 3ds max™ the topics in this book supplement the main 3ds max MAXScript Reference. These topics list specific differences between MAXScript for gmax and 3ds max. There are several non-game related globals, classes, methods, interfaces that are not supported in gmax. There are also additions that have been made to support the more game intensive features. Additionally you will find several restrictions that have been placed on various aspects of MAXScript.

Globals, Classes, Methods, and Interfaces Not Supported in gmax

Additional Classes and Globals Defined in gmax

Documentation for New Methods, Classes, Interfaces in gmax


Globals, Classes, Methods, and Interfaces Not Supported in gmax

Globals

Binding Space Warp Objects | bindSpaceWarp | NodeGeneric
Camera Tracker | closeCameraTracker | Primitive
Bitmaps | display | Generic
Bitmaps | save | Generic
Bitmaps | setPixels | Generic
Bitmaps | setIndexedPixels | Generic
Depth of Field Render Effect | DOF | StructDef
Depth of Field Render Effect | DOF.addCam | Primitive
Depth of Field Render Effect | DOF.addFocalNode | Primitive
Depth of Field Render Effect | DOF.deleteCam | Primitive
Depth of Field Render Effect | DOF.deleteCamByName | Primitive
Depth of Field Render Effect | DOF.deleteFocalNode | Primitive
Depth of Field Render Effect | DOF.deleteFocalNodeByName | Primitive
Editable Patch | patch.getMeshStepsRender | Primitive
Editable Patch | patch.setMeshStepsRender | Primitive
Files | copyFile | Primitive
Files | createFile | Primitive
Files | encryptFile | Primitive
Files | makeDir | Primitive
Files | openEncryptedFile | Primitive
Files | openlog | Primitive
Files | renameFile | Primitive
Files | setFileAttribute | Primitive
Files | setINISetting | Primitive
Flex modifier | flexOps | StructDef
Flex modifier | flexOps.ClearEdgeVertices | Primitive
Flex modifier | flexOps.GetNumberVertices | Primitive
Flex modifier | flexOps.GetVertexWeight | Primitive
Flex modifier | flexOps.isEdgeVertex | Primitive
Flex modifier | flexOps.SelectVertices | Primitive
Flex modifier | flexOps.SetEdgeVertices | Primitive
Flex modifier | flexOps.SetVertexWeights | Primitive
Lens Effects | LE | StructDef
Lens Effects | LE.addASec | Primitive
Lens Effects | LE.addGlow | Primitive
Lens Effects | LE.addLight | Primitive
Lens Effects | LE.addLightNode | Primitive
Lens Effects | LE.addMSec | Primitive
Lens Effects | LE.addRay | Primitive
Lens Effects | LE.addRing | Primitive
Lens Effects | LE.addStar | Primitive
Lens Effects | LE.addStreak | Primitive
Lens Effects | LE.deleteElement | Primitive
Lens Effects | LE.deleteElementByName | Primitive
Lens Effects | LE.deleteLight | Primitive
Lens Effects | LE.deleteLightByName | Primitive
Lens Effects | LE.lightIndex | Primitive
Lens Effects | LE.lightName | Primitive
Lens Effects | LE.load | Primitive
Lens Effects | LE.numLights | Primitive
Lens Effects | LE.save | Primitive
Material Libraries | FileSaveAsMatLib | Primitive
Material Libraries | FileSaveMatLib | Primitive
Material Libraries | SaveMaterialLibrary | Primitive
MAXScript Editor | newScript | Primitive
gmax Files | saveNodes | Primitive
NURBS | addNURBSSet | NodeGeneric
NURBS | appendCurve | Generic
NURBS | appendCurveByID | Generic
NURBS | appendObject | Generic
NURBS | appendUCurve | Generic
NURBS | appendUCurveByID | Generic
NURBS | appendVCurve | Generic
NURBS | appendVCurveByID | Generic
NURBS | breakCurve | NodeGeneric
NURBS | breakSurface | NodeGeneric
NURBS | clearProdTess | Generic
NURBS | clearViewTess | Generic
NURBS | closeU | Generic
NURBS | closeV | Generic
NURBS | convertToNURBSCurve | NodeGeneric
NURBS | convertToNURBSSurface | NodeGeneric
NURBS | deleteObjects | Generic
NURBS | disconnect | Generic
NURBS | evalPos | Generic
NURBS | evalTangent | Generic
NURBS | evalUTangent | Generic
NURBS | evalVTangent | Generic
NURBS | getCurve | Generic
NURBS | getCurveID | Generic
NURBS | getCurveStartPoint | Generic
NURBS | getCV | Generic
NURBS | getEdge | Generic
NURBS | getFlip | Generic
NURBS | getFlipTrim | Generic
NURBS | getGenerateUVs | Generic
NURBS | getKnot | Generic
NURBS | getNURBSSet | NodeGeneric
NURBS | getObject | Generic
NURBS | getParent | Generic
NURBS | getParentID | Generic
NURBS | getPoint | Generic
NURBS | getProdTess | Generic
NURBS | getRadius | Generic
NURBS | getSeed | Generic
NURBS | getTextureSurface | Generic
NURBS | getTextureUVs | Generic
NURBS | getTiling | Generic
NURBS | getTilingOffset | Generic
NURBS | getTrimSurface | Generic
NURBS | getUCurve | Generic
NURBS | getUCurveID | Generic
NURBS | getUKnot | Generic
NURBS | getVCurve | Generic
NURBS | getVCurveID | Generic
NURBS | getViewTess | Generic
NURBS | getVKnot | Generic
NURBS | joinCurves | NodeGeneric
NURBS | joinSurfaces | NodeGeneric
NURBS | makeIndependent | NodeGeneric
NURBS | MakeNURBSConeSurface | Primitive
NURBS | MakeNURBSCylinderSurface | Primitive
NURBS | MakeNURBSLatheSurface | Primitive
NURBS | MakeNURBSSphereSurface | Primitive
NURBS | MakeNURBSTorusSurface | Primitive
NURBS | NURBSExtrudeNode | Primitive
NURBS | NURBSLatheNode | Primitive
NURBS | NURBSNode | Primitive
NURBS | refine | Generic
NURBS | refineU | Generic
NURBS | refineV | Generic
NURBS | reparameterize | Generic
NURBS | setCurve | Generic
NURBS | setCurveByID | Generic
NURBS | setCurveStartPoint | Generic
NURBS | setCV | Generic
NURBS | setEdge | Generic
NURBS | setFlip | Generic
NURBS | setFlipTrim | Generic
NURBS | setGenerateUVs | Generic
NURBS | setKnot | Generic
NURBS | setObject | Generic
NURBS | setParent | Generic
NURBS | setParentID | Generic
NURBS | setPoint | Generic
NURBS | setProdTess | Generic
NURBS | setRadius | Generic
NURBS | setRenderApproximation | NodeGeneric
NURBS | setSeed | Generic
NURBS | setSurfaceDisplay | NodeGeneric
NURBS | setTextureSurface | Generic
NURBS | setTextureUVs | Generic
NURBS | setTiling | Generic
NURBS | setTilingOffset | Generic
NURBS | setTrimSurface | Generic
NURBS | setUCurve | Generic
NURBS | setUCurveByID | Generic
NURBS | setUKnot | Generic
NURBS | setVCurve | Generic
NURBS | setVCurveByID | Generic
NURBS | setViewApproximation | NodeGeneric
NURBS | setViewTess | Generic
NURBS | setVKnot | Generic
OLE | createOLEObject | Primitive
Operating System | DOSCommand | Primitive
Operating System | ShellLaunch | Primitive
Operating System | Windows.sendMessage | Primitive
Particle Systems | particleAge | NodeGeneric
Particle Systems | particleCount | NodeGeneric
Particle Systems | particlePos | NodeGeneric
Particle Systems | particleSize | NodeGeneric
Particle Systems | particleVelocity | NodeGeneric
Preview Rendering | CreatePreview | Primitive
RAM Player | RAMPlayer | Primitive
Reactor Controllers | createReaction | Primitive
Reactor Controllers | deleteReaction | Primitive
Reactor Controllers | getReactionCount | Primitive
Reactor Controllers | getReactionFalloff | Primitive
Reactor Controllers | getReactionInfluence | Primitive
Reactor Controllers | getReactionName | Primitive
Reactor Controllers | getReactionState | Primitive
Reactor Controllers | getReactionStrength | Primitive
Reactor Controllers | getReactionValue | Primitive
Reactor Controllers | getSelectedReactionNum | Primitive
Reactor Controllers | reactTo | Primitive
Reactor Controllers | setReactionFalloff | Primitive
Reactor Controllers | setReactionInfluence | Primitive
Reactor Controllers | setReactionName | Primitive
Reactor Controllers | setReactionState | Primitive
Reactor Controllers | setReactionStrength | Primitive
Reactor Controllers | setReactionValue | Primitive
Rendering | render | Primitive
Schematic View | schematicView | StructDef
Schematic View | schematicView.close | Primitive
Schematic View | schematicView.getSchematicViewName | Primitive
Schematic View | schematicView.numSchematicViews | Primitive
Schematic View | schematicView.open | Primitive
Schematic View | schematicView.zoomSelected | Primitive
Schematic View | selectReaction | Primitive
Skin modifier | skinOps.saveEnvelope | Primitive
Surface Mapper space warp modifier | updateSurfaceMapper | Primitive
Terrain object | terrainOps | StructDef
Terrain object | terrainOps.addOperand | Primitive
Terrain object | terrainOps.deleteOperand | Primitive
Terrain object | terrainOps.getOperand | Primitive
Terrain object | terrainOps.getOperandTM | Primitive
Terrain object | terrainOps.setOperandTM | Primitive
Terrain object | terrainOps.update | Primitive
Video Post | videoPostTracks | MAXTVNode
Viewports | displaySafeFrames | BooleanClass

Classes

NURBS1RailSweepSurface | Class | NURBS
NURBS2RailSweepSurface | Class | NURBS
NURBSBlendCurve | Class | NURBS
NURBSBlendSurface | Class | NURBS
NURBSCapSurface | Class | NURBS
NURBSChamferCurve | Class | NURBS
NURBSControlVertex | Class | NURBS
NURBSCurve | Class | NURBS
NURBSCurveConstPoint | Class | NURBS
NURBSCurveIntersectPoint | Class | NURBS
NURBSCurveOnSurface | Class | NURBS
NURBSCurveSurfaceIntersectPoint | Class | NURBS
NURBSCVCurve | Class | NURBS
NURBSCVSurface | Class | NURBS
NURBSDisplay | Class | NURBS
NURBSExtrudeSurface | Class | NURBS
NURBSFilletCurve | Class | NURBS
NURBSFilletSurface | Class | NURBS
NURBSIndependentPoint | Class | NURBS
NURBSIsoCurve | Class | NURBS
NURBSLatheSurface | Class | NURBS
NURBSMirrorCurve | Class | NURBS
NURBSMirrorSurface | Class | NURBS
NURBSMultiCurveTrimSurface | Class | NURBS
NURBSNBlendSurface | Class | NURBS
NURBSObject | Class | NURBS
NURBSOffsetCurve | Class | NURBS
NURBSOffsetSurface | Class | NURBS
NURBSPoint | Class | NURBS
NURBSPointConstPoint | Class | NURBS
NURBSPointCurve | Class | NURBS
NURBSPointCurveOnSurface | Class | NURBS
NURBSPointSurface | Class | NURBS
NURBSProjectNormalCurve | Class | NURBS
NURBSProjectVectorCurve | Class | NURBS
NURBSRuledSurface | Class | NURBS
NURBSSelection | Class | NURBS
NURBSSet | Class | NURBS
NURBSSurface | Class | NURBS
NURBSSurfaceApproximation | Class | NURBS
NURBSSurfaceEdgeCurve | Class | NURBS
NURBSSurfaceNormalCurve | Class | NURBS
NURBSSurfConstPoint | Class | NURBS
NURBSSurfSurfIntersectionCurve | Class | NURBS
NURBSTexturePoint | Class | NURBS
NURBSTextureSurface | Class | NURBS
NURBSULoftSurface | Class | NURBS
NURBSUVLoftSurface | Class | NURBS
NURBSXFormCurve | Class | NURBS
NURBSXFormSurface | Class | NURBS

MAXClasses

Adobe_Photoshop_Plug_In_Filter | textureMap
Adobe_Premiere_Video_Filter | textureMap
Alpha | RenderElement
alphaRenderElement | RenderElement
Anchor | helper
Anisotropic | Shader
Apollo_Param_Container | GeometryClass
apolloParamContainer | GeometryClass
App_Data_Tester | UtilityPlugin
ASCII_Object_Output | UtilityPlugin
Atmosphere | RenderElement
atmosphereRenderElement | RenderElement
AudioClip | helper
AudioFloat | FloatController
AudioPoint3 | Point3Controller
AudioPosition | PositionController
AudioRotation | RotationController
AudioScale | ScaleController
Auto_Secondary_Element | ReferenceTarget
Autodesk_Animator_Flic | BitmapIO
Automatic_Exposure_Control | ToneOperator
AutomaticAdaptiveExposureControl | ToneOperator
AVI | BitmapIO
Background | helper
BackgroundRenderElement | RenderElement
Beauty | RenderElement
beautyRenderElement | RenderElement
BendModWSM | SpacewarpObject
Bevel | modifier
Bevel_Profile | modifier
bgndRenderElement | RenderElement
Billboard | helper
BlendRenderElement | RenderElement
Blizzard | GeometryClass
BoxGizmo | helper
blur | renderEffect
Bomb | SpacewarpObject
Bombbinding | SpacewarpModifier
Bricks | textureMap
Brightness_and_Contrast | renderEffect
briteCon | renderEffect
C___Object_Output | UtilityPlugin
C_Ext | GeometryClass
Camera_Match | UtilityPlugin
Camera_Tracker | UtilityPlugin
CameraMap | modifier
CameraMapSpaceWarp | SpacewarpObject
CamPoint | helper
Capsule | GeometryClass
Cellular | textureMap
cellularTex | textureMap
ChamferBox | GeometryClass
ChamferCyl | GeometryClass
CIN | BitmapIO
CMB | BitmapIO
collapse | UtilityPlugin
Color_Balance | renderEffect
Color_Clipboard | UtilityPlugin
colorBalance | renderEffect
COM_DCOM_Server_Control | UtilityPlugin
Combustion | textureMap
Compass | helper
ConformSpaceWarp | SpacewarpObject
CV_Curve | shape
CV_Curveshape | shape
CV_Surf | GeometryClass
CylGizmo | helper
Damper | GeometryClass
Deflector | SpacewarpObject
Deflectorbinding | SpacewarpModifier
Dent | textureMap
dents | textureMap
Depth_of_Field | renderEffect
Depth_of_FieldMPassCamEffect | MPassCamEffect
Diffuse | RenderElement
diffuseRenderElement | RenderElement
Disp_Approx | modifier
Displace_Mesh | SpacewarpModifier
Displace_NURBS | SpacewarpModifier
Displacebinding | SpacewarpModifier
DOFEffect | renderEffect
Drag | SpacewarpObject
DragMod | SpacewarpModifier
Dynamics | UtilityPlugin
Dynamics_Position_Controller | PositionController
Dynamics_Rotation_Controller | RotationController
emissionRenderElement | RenderElement
EPS_Image | BitmapIO
fallofftextureMap | textureMap
FFD_Binding | SpacewarpModifier
FFD_Select | modifier
File_Output | renderEffect
fileOut | renderEffect
Fillet_Chamfer | modifier
Film_Grain | renderEffect
FilmGrain | renderEffect
Fire_Effect | atmospheric
Flex | modifier
Float_Motion_Capture | FloatController
Float_Reactor | FloatController
FloatReactor | FloatController
Fog | atmospheric
FogHelper | helper
Gengon | GeometryClass
GIF | BitmapIO
Glow_Element | ReferenceTarget
Gradient_GradCtlData | ReferenceTarget
Gradient_Ramp | textureMap
gravity | SpacewarpObject
Gravitybinding | SpacewarpModifier
Hedra | GeometryClass
Hose | GeometryClass
HSDS_Modifier | modifier
HSDSObject | modifier
IFL | BitmapIO
IFL_Manager | UtilityPlugin
IKHISolver | IKSolver
imageMotionBlur | renderEffect
Inline | helper
JAngleData | ReferenceTarget
JBinaryData | ReferenceTarget
JBoolData | ReferenceTarget
JColor3Data | ReferenceTarget
JColorData | ReferenceTarget
JFlagCtlData | ReferenceTarget
JFlagSetData | ReferenceTarget
JFloat3Data | ReferenceTarget
JFloatData | ReferenceTarget
JGradCtlData | ReferenceTarget
Joystick_Input_Device | ReferenceTarget
JPercent3Data | ReferenceTarget
JPercentData | ReferenceTarget
JSubtex | ReferenceTarget
JWorld3Data | ReferenceTarget
JWorldData | ReferenceTarget
L_Ext | GeometryClass
Lattice | modifier
Lens_Effects | renderEffect
Level_of_Detail | UtilityPlugin
Lines | shape
Link_Inheritance__Selected | UtilityPlugin
LOD | helper
LOD_Controller | FloatController
LZFlare_AutoSec_Base | ReferenceTarget
LZFlare_AutoSec_Data | ReferenceTarget
LZFlare_Aux_Data | ReferenceTarget
LZFlare_Data | ReferenceTarget
LZFlare_Glow_Data | ReferenceTarget
LZFlare_Inferno_Data | ReferenceTarget
LZFlare_ManSec_Base | ReferenceTarget
LZFlare_ManSec_Data | ReferenceTarget
LZFlare_Prefs_Data | ReferenceTarget
LZFlare_Rays_Data | ReferenceTarget
LZFlare_Rend_Data | ReferenceTarget
LZFlare_Ring_Data | ReferenceTarget
LZFlare_Star_Data | ReferenceTarget
LZFlare_Streak_Data | ReferenceTarget
LZFocus_Data | ReferenceTarget
LZGlow_Aux_Data | ReferenceTarget
LZGlow_Data | ReferenceTarget
LZGlow_Rend_Data | ReferenceTarget
LZHilight_Aux_Data | ReferenceTarget
LZHilight_Data | ReferenceTarget
LZHilight_Rend_Data | ReferenceTarget
Manual_Secondary_Element | ReferenceTarget
MaterialByElement | modifier
MAX_File_Finder | UtilityPlugin
MaxRenderer_COM_Server | GlobalUtilityPlugin
Measure | UtilityPlugin
Melt | modifier
MeshCollision | ReferenceMaker
Mesher | GeometryClass
MIDI_Device | ReferenceTarget
Motion_Blur | renderEffect
Motion_BlurMPassCamEffect | MPassCamEffect
Motion_Capture | UtilityPlugin
Motor | SpacewarpObject
MotorMod | SpacewarpModifier
Mouse_Input_Device | ReferenceTarget
Multi_Layer | Shader
MultiLayer | Shader
multiPassDOF | MPassCamEffect
multiPassMotionBlur | MPassCamEffect
MultiRes | modifier
NavInfo | helper
NCurve_Sel | modifier
NSurf_Sel | modifier
NURBS_API_Test | UtilityPlugin
NURBS_Imported_Objects | GeometryClass
Nurbs | GeometryClass
NURBSCurveShape | shape
OilTank | GeometryClass
Oren_Nayar_Blinn | Shader
OrenNayarBlinn | Shader
PArray | GeometryClass
Particle_Age | textureMap
Particle_Cache | SpacewarpModifier
Particle_MBlur | textureMap
particleBlur | textureMap
ParticleCache | SpacewarpModifier
particleMesher | GeometryClass
Path_Follow | SpacewarpObject
Path_FollowMod | SpacewarpModifier
PathDeformSpaceWarp | SpacewarpObject
PBomb | SpacewarpObject
PBombMod | SpacewarpModifier
PCloud | GeometryClass
PDynaFlect | SpacewarpObject
PDynaFlectMod | SpacewarpModifier
PDynaflector | SpacewarpObject
Perlin_Marble | textureMap
perlinMarble | textureMap
PlanarCollision | ReferenceMaker
Planet | textureMap
Plug_in_Manager | GlobalUtilityPlugin
pngio | BitmapIO
Point3_Motion_Capture | Point3Controller
Point3_Reactor | Point3Controller
Point3Reactor | Point3Controller
Point3Spring | Point3Controller
Point_Cache | modifier
Point_CacheSpacewarpModifier | SpacewarpModifier
Point_Curve | shape
Point_Curveshape | shape
Point_Surf | GeometryClass
Point_SurfGeometry | GeometryClass
PointCache | modifier
PointCacheWSM | SpacewarpModifier
POmniFlect | SpacewarpObject
POmniFlectMod | SpacewarpModifier
Portable_Network_Graphics | BitmapIO
Position_Motion_Capture | PositionController
Position_Reactor | PositionController
PositionReactor | PositionController
PositionSpring | PositionController
Prism | GeometryClass
ProxSensor | helper
PSD_I_O | BitmapIO
PushMod | SpacewarpModifier
PushSpaceWarp | SpacewarpObject
Pyramid | GeometryClass
QTime | BitmapIO
Ray_Element | ReferenceTarget
Ray_Engine | ReferenceTarget
Raytrace | textureMap
Raytrace_Engine_Global_Parameters | ReferenceTarget
Raytrace_Texture_ParamBlock | ReferenceTarget
RaytraceMaterial | material
Reflection | RenderElement
reflectionRenderElement | RenderElement
Refraction | RenderElement
refractionRenderElement | RenderElement
Rescale_World_Units | UtilityPlugin
rgb | BitmapIO
Ring_Element | ReferenceTarget
RingWave | GeometryClass
Ripplebinding | SpacewarpModifier
RLA | BitmapIO
RmModel | GeometryClass
RmModelGeometry | GeometryClass
Rotation_Motion_Capture | RotationController
Rotation_Reactor | RotationController
RotationReactor | RotationController
RPF | BitmapIO
Scale_Motion_Capture | ScaleController
Scale_Reactor | ScaleController
ScaleReactor | ScaleController
SDeflectMod | SpacewarpModifier
SDeflector | SpacewarpObject
SDynaFlect | SpacewarpObject
SDynaFlectMod | SpacewarpModifier
SDynaflector | SpacewarpObject
section | shape
Self_Illumination | RenderElement
ShadowRenderElement | RenderElement
Shape_Check | UtilityPlugin
Shellac | material
SimpleOSMToWSMMod | SpacewarpModifier
SlidingDoor | GeometryClass
SlidingWindow | GeometryClass
Smoke | textureMap
Snow | GeometryClass
SOmniFlect | SpacewarpObject
SOmniFlectMod | SpacewarpModifier
Sound | helper
SpaceBend | SpacewarpObject
SpaceCameraMap | SpacewarpModifier
SpaceConform | SpacewarpModifier
Spacedisplace | SpacewarpObject
SpaceFFDBox | SpacewarpObject
SpaceFFDCyl | SpacewarpObject
SpaceNoise | SpacewarpObject
SpacePatchDeform | SpacewarpModifier
SpacePathDeform | SpacewarpModifier
Spaceripple | SpacewarpObject
SpaceSkew | SpacewarpObject
SpaceStretch | SpacewarpObject
SpaceSurfDeform | SpacewarpModifier
SpaceTaper | SpacewarpObject
SpaceTwist | SpacewarpObject
Spacewave | SpacewarpObject
Speckle | textureMap
Specular | RenderElement
specularRenderElement | RenderElement
SphereGizmo | helper
SphericalCollision | ReferenceMaker
Spherify | modifier
Spindle | GeometryClass
Splat | textureMap
Spray | GeometryClass
Spring | GeometryClass
SpringPoint3Controller | Point3Controller
SpringPositionController | PositionController
Squeeze | modifier
Star_Element | ReferenceTarget
STL_Check | modifier
Strauss | Shader
Streak_Element | ReferenceTarget
Stretch | modifier
Strokes | UtilityPlugin
Stucco | textureMap
Sunlight | System
Sunlight_Slave_Controller | PositionController
SuperSpray | GeometryClass
Surface_Approximation | UtilityPlugin
Surface_Mapper | SpacewarpModifier
SurfDeform | modifier
Swirl | textureMap
Terrain | GeometryClass
TexmapsReferenceMaker | ReferenceMaker
This_Data | ReferenceTarget
TimeSensor | helper
Torus_Knot | GeometryClass
TouchSensor | helper
Trim_Extend | modifier
TVDummyControl | Matrix3Controller
UDeflector | SpacewarpObject
UDeflectorMod | SpacewarpModifier
UDynaDeflector | SpacewarpObject
UDynaFlect | SpacewarpObject
UDynaFlectMod | SpacewarpModifier
UOmniFlect | SpacewarpObject
UOmniFlectMod | SpacewarpModifier
Utility_Tester | UtilityPlugin
videoPostTracks | MAXTVNode
Volume_Fog | atmospheric
Volume_Light | atmospheric
Vortex | SpacewarpObject
VortexMod | SpacewarpModifier
VUE_File_Renderer | RendererClass
Water | textureMap
Wavebinding | SpacewarpModifier
Waveform_Float | FloatController
Wind | SpacewarpObject
Windbinding | SpacewarpModifier
Wood | textureMap
YUV | BitmapIO
Z_Depth | RenderElement
ZRenderElement | RenderElement

Interfaces

HDIKSys | Interface
netrender | Interface
pluginManager | Interface
NetCreateHelpers | Interface

Restrictions

Cannot save or export more than 1000 gmax or material library files per session.

Cannot save the cui config file using cui.saveConfig or cui.saveConfigAs more than 1000 times per session.

Strings are limited to 15000 characters.

The path string argument for mapPaths.add and xrefPaths.add is limited to 260 characters.

The number of selected characters in Listener is limited to 10000 characters.

External files cannot be opened in append or write mode.

The number of bitmap path directories is limited to 500.

The following max commands are not supported in gmax:

  • max render scene

  • max render last

  • max quick render

  • max preview

  • max rename preview

  • max safeframe toggle

  • max videopost

The following camera properties are not supported in gmax:

  • <camera>.mpassEnabled

  • <camera>.mpassRenderPerPass

  • <camera>.mpassEffect

Only the Macromedia Flash™ Player (Program ID "ShockwaveFlash.ShockwaveFlash.", Class ID {D27CDB6E-AE6D-11CF-96B8-444553540000}) is supported as an activeXControl UI item.


Additional Classes and Globals Defined in gmax

Custom User Interface | cui.dockDialogBar | Primitive
Custom User Interface | cui.floatDialogBar | Primitive
Custom User Interface | cui.getDockState | Primitive
Custom User Interface | cui.registerDialogBar | Primitive
Custom User Interface | cui.setAppTitle | Primitive
Custom User Interface | cui.unRegisterDialogBar | Primitive
External file utility | getFileSize | Primitive
MAX utility method | getMAXWindowSize | Primitive
String parser method | isSpace | Primitive
String parser method | peekToken | Primitive
String parser method | readToken | Primitive
String parser method | skipSpace | Primitive
String parser method | trimLeft | Primitive
String parser method | trimRight | Primitive
SubRollout class | AddSubRollout | Primitive
SubRollout class | RemoveSubRollout | Primitive

Classes

SubRollout | Class | UI element
gmax_File_Finder | Utility Plugin |
Missing_Shadow_Type | (max bug fix) |

Interface Methods

Interface: colorMan (new methods)

<boolean>SaveIconFile <filename>szFilename <filename>szIconPath

<boolean>LoadIconFile <filename>szFilename

<string>ReadIconFile()

Interface: quadMenuSettings (new methods)

<void>SaveSettingsFile <filename>szFilename

<void>LoadSettingsFile <filename>szFilename

Interface: gridPrefs

Properties:

.spacing : float : Read|Write

.majorLines : integer : Read|Write

Methods:

Actions:

Interface: statusPanel

Properties:

Methods:

<void>setVisible <boolean>visible

<boolean>isVisible()

Actions:

Interface: memStreamMgr

Properties:

Methods:

<Interface>openFile <string>fname

<Interface>openString <string>string

<void>close <Interface>memStream

Actions:

Interface: memStream (returned from memStreamMgr.openString(), memStreamMgr.openFile())

Properties:

Methods:

<string>getFileName()

<void>skipSpace()

<string>readChar()

<string>peekChar()

<string>readLine()

<string>readToken()

<string>peekToken()

<void>unReadToken()

<string>readBlock <string>open <string>close

<void>skipBlock <string>open <string>close

<integer>pos()

<void>seek <integer>offset <enum>origin

origin enums: {#seek_set|#seek_cur|#seek_end}

<integer>size()

<bool>eos()

Actions:


Documentation for New Methods, Classes, Interfaces in gmax

SubRollout Class

SubRollout

Subclass of RolloutControl. All Rollout User-Interface Controls Common Properties and Rollout User-Interface Controls Common Layout Parameters should apply.

Description

A UI item into which you can place rollouts. No caption is displayed for the UI item. On right side of the UI item a scrollbar is displayed if the height of the rollout(s) in the item is greater than the height of the item.

Additional Properties

rollouts - the rollouts installed in the SubRollout control via AddSubRollout - see notes below. Read-only.

The names of the installed rollouts are exposed as read-only properties.

Notes on common UI item properties:

  • caption - none displayed. Read/write.

  • text - none displayed. Read/write.

  • enabled – setting has no effect. Always set to true. Read/Write.

  • pos - the position of the UI item in the rollout. Read/write.

  • align - UI item alignment. Creation only property.

  • offset - UI item offset. Creation only property.

  • width - Sets the width of the subrollout. Accessible as property of the UI item. No other UI element exposes this property other than during creation

  • height - Sets the width of the subrollout. Accessible as property of the UI item. No other UI element exposes this property other than during creation

  • across – Number of UI items across. Creation only property.

Associated Methods

AddSubRollout <subrollout> <rollout> [rolledUp:<boolean>]

Adds the rollout to the subrollout. Always returns ok.

RemoveSubRollout <subrollout> <rollout>

Removes the rollout from the subrollout. Always returns ok.

Example

rollout test "test" height:200

( subrollout test1 "test1"

subrollout test2 "test2"

)

rollout test1a "test1a"

( spinner test1as "test1as"

)

rollout test1b "test1b"

( spinner test1bs "test1bs"

)

createdialog test

AddSubRollout test.test1 test1a

AddSubRollout test.test1 test1b

test.test1.height += 100

test.test2.pos += [0,100]

rollout test2a "test2a"

( spinner test2as "test2as"

)

AddSubRollout test.test2 test2a

test.test2.height += 50

Notes

Changing the height of a subRollout doesn't change the position of any UI items below it.

External File Utility/MAX Utility Methods

<Integer> getFileSize <filename_string>

Returns the size of the specified file in bytes, 0 if the file is not found.

<Point2> getMAXWindowSize()

Returns the 3ds max window size in pixels.

String Parser Methods

<Boolean> isSpace <String>

Returns true if the first character of the given string is whitespace (space, tab, or newline), false if not.

<String> trimLeft <String> [String trimChars]

Trims all leading characters specified in trimChars from the given string and returns it. If trimChars is not specified, basic whitespace characters (space, tab, and newlines) are trimmed.

<String> trimRight <String> [String trimChars]

Trims all trailing characters specified in trimChars from the given string and returns it. If trimChars is not specified, basic whitespace characters (space, tab, and newlines) are trimmed.

<String> readToken <CharStream>

Reads a token from the given stream and returns it as a string. Tokens are defined by a sequence of characters broken up by whitespace. Leading whitespace and one line "//" style comments are automatically skipped.

<String> peekToken <CharStream>

Same as readToken except it does not increment the file position.

Example

a= "token! -- /* comment!\n */ ( ( \"nested bracket\" pair ) ) " as stringstream

(while peekToken a != undefined do print (readToken a);ok)

skipSpace <CharStream>

Skips to first non-whitespace from the given stream's current file position.

Custom User Interface - Structure (New Methods)

cui.RegisterDialogBar <RolloutFloater_or_Rollout> [minSize:<Point2>] [maxSize:<Point2>] [style:<Array>]

This method registers a MAXScript window as a dockable CUI window in MAX.

Parameters

<RolloutFloater_or_Rollout>

This parameter must be a RolloutFloater created with NewRolloutFloater or a Rollout that has been installed in a dialog using CreateDialog.

[minSize:<Point2>] -- default: size of the floater or dialog that was passed.

Minimum size the dialog bar can be.

[maxSize:<Point2>] -- default: size of the floater or dialog that was passed.

Maximum size that the dialog bar can be. Values of -1 passed mean that the dialogbar can size and stretch.

[style:<Array>] -- default:#(#cui_dock_all, #cui_floatable, #cui_handles)

Array of style flags, can be one or more of the following:

#cui_dock_all -- dialog bar can dock on all 4 edges of the frame.
#cui_dock_horz -- can dock horizontally (top and bottom)
#cui_dock_vert -- can dock vertically (left and right)
#cui_dock_left -- can dock to the left
#cui_dock_top -- can dock to the top
#cui_dock_right -- can dock to the right
#cui_dock_bottom -- can dock to the bottom
#cui_floatable -- dialogbar can float
#cui_handles -- show gripper handles when docked

Notes

A rollout that has been registered as a dialog bar cannot be destroyed using destroyDialog, or moved using setDialogPos. The rollout must be unregistered first.

A rollout floater that has been registered as a dialog bar cannot closed using closeRolloutFloater, its position changed using the rollout floater's pos property, or size changed with the rollout floater's size property. The rollout floater must be unregistered first.

A new read-only property has been added to the Rollout and RolloutFloater classes: dialogBar. This property will be true if the rollout or rollout floater has been registered using this method.

cui.UnRegisterDialogBar <RolloutFloater_or_Rollout>

This method un-registers a dockable MAXScript window.

Parameters

<RolloutFloater_or_Rollout>

This parameter must be a RolloutFloater created with NewRolloutFloater or a Rollout that has been installed in a dialog using CreateDialog, and has been registered using cui.RegisterDialogBar.

cui.DockDialogBar <RolloutFloater_or_Rollout> <dockflag>

This method docks a registered dialog bar to the specified docking area.

Parameters

<RolloutFloater_or_Rollout>

This parameter must be a RolloutFloater created with NewRolloutFloater or a Rollout that has been installed in a dialog using CreateDialog, and has been registered using cui.RegisterDialogBar.

<dockflag>Specifies the area to dock the dialog bar to. Can be one of the following:

#cui_dock_left -- dock to the left
#cui_dock_top -- dock to the top
#cui_dock_right -- dock to the right
#cui_dock_bottom -- dock to the bottom

cui.FloatDialogBar <RolloutFloater_or_Rollout>

This method will float a registered dialog bar.

Parameters

<RolloutFloater_or_Rollout>

This parameter must be a RolloutFloater created with NewRolloutFloater or a Rollout that has been installed in a dialog using CreateDialog, and has been registered using cui.RegisterDialogBar.

cui.getDockState <RolloutFloater_or_Rollout>

This method returns the current dock state of the registered dialog bar.

Parameters

<RolloutFloater_or_Rollout>

This parameter must be a RolloutFloater created with NewRolloutFloater or a Rollout that has been installed in a dialog using CreateDialog, and has been registered using cui.RegisterDialogBar.

Output

The current dock state of the given dialog bar as:

#cui_dock_left

#cui_dock_top

#cui_dock_right

#cui_dock_bottom

#cui_floatable

cui.setAppTitle <string>

This method sets the title bar of the main 3ds max window to the specified string.

Parameters

<string>

The string to be displayed in the title bar of the main 3ds max window

Interface Methods

memStreamMgr - Interface

Description

An interface that exposes methods for opening and closing memStream interfaces. The memStreamMgr and memStream interfaces provide fast stream parsing, loading entire files into memory.

Methods

<Interface>openFile <string>fname

Returns a memStream interface where the content of the specified file is the input stream to be processed. If the file cannot be opened, a value of undefined is returned.

<Interface>openString <string>string

Returns a memStream interface where the content of the string is the input stream to be processed.

<void>close <Interface>memStream

Closes the input stream for the memStream, freeing the memory associated with this stream.

memStream - Interface

Description

Provides methods for parsing the input stream. This interface is returned from the memStreamMgr.openString() and memStreamMgr.openFile() methods.

Methods

<string>getFileName()

Returns the file name that the memStream was created from. Returns "" if the interface was created via memStreamMgr.openString().

<void>skipSpace()

Skips leading whitespace characters (space, tab, and newlines) starting at the current stream cursor position. Following this call the stream cursor position will be at a non-whitespace character, or at the end of the stream.

<string>readChar()

Reads a single character from the stream, returning it as a string.

<string>peekChar()

Reads a single character from the stream, returning it as a string. Does not increment the stream cursor position.

<string>readLine()

Reads all characters from the current stream cursor position until a newline and returns it as a string.

<string>readToken()

Reads a token from the given stream returns it as a string. A token is defined by a sequence of characters surrounded by whitespace or the stream start or end. Leading whitespace and one line "//" style comments are automatically skipped.

The maximum allowed length of the returned string is 5120 characters. If a token larger than this length is read, the string returned contains the first 5120 characters of the token. The stream cursor position will be at the next character.

<string>peekToken()

Same as <memStream>.readToken except it does not increment the stream cursor position.

<void>unReadToken()

Resets the stream cursor position to right before the last readToken operation.

<string>readBlock <string>open <string>close

Reads a block of tokens from the 'open' token until the 'close' token, automatically skipping nested open/close token pairs, and returns the contents as a string. This string will contain the initial 'open' token and the final 'close' token. The initial 'open' token must be the next token in the input stream. If it is not, a value of 'undefined' will be returned.

Following this call, the stream cursor position will be at the beginning of the next token, or at the end of the stream if there are no more tokens following the 'close' token. The comparison of tokens against the 'open' and 'close' tokens is case-insensitive.

Note that the open and close strings represent tokens, and not character strings. For example:

b2=memStreamMgr.openstring "{aaaaa}"

b2.readblock "{" "}"

will return undefined, because the '{' and '}' are not surrounded by whitespace, and so are not found as tokens (the entire content of the memStream is a single token).

If the 'open' token is not the next token in the input stream, a value of 'undefined' will be returned, and the stream cursor position will be unchanged.

If the 'open' token is the next token in the input stream, but the 'close' token is not found, returns a string starting at the open token, and ending at the end of stream -1 character.

The maximum allowed length of the block is 5120 characters. If a block is found, but is larger than this length, a value of 'undefined' is returned. However, the stream cursor position will be at the end of the block.

<void>skipBlock <string>open <string>close

Same as readBlock except does not return the block of tokens (this is a little faster).

<integer>pos()

Returns the current stream cursor position.

<void>seek <integer>offset <enum>origin

origin enums: {#seek_set|#seek_cur|#seek_end}

Moves stream cursor position 'offset' number of characters from the base specified.

#seek_set - start of file

#seek_cur - current file position

#seek_end - end of file (works with negative offset values)

<integer>size()

Returns the size of the input stream

<bool>eos()

Returns true if the current stream cursor position is at or past the end of the input stream, false otherwise.

Example

ms = memStreamMgr.openString "token! //comment!\n { { nested bracket pair } } "

ms.readToken()

ms.readBlock "{" "}"

ms.eos()

memStreamMgr.close ms

Result

<MixinInterface:memStream>

"token!"

"{ { nested bracket pair } }"

true

OK

Notes

The read or peek methods currently do not protect against reading past the end of the input stream.

The seek method currently does not protect against setting position past end of the input stream.

The readBlock and skipBlock methods performs case-insensitive comparisons on the open and close token strings.

Interface: colorMan (new methods)

<boolean>SaveIconFile <filename>szFilename <filename>szIconPath

This method saves the szIconPath path string to the specified file. If no path is specified in szFilename, the file will be stored in current CUI directory. The maximum allowed string length for szIconPath is 260 characters. If the specified file already exists, its contents will be overwritten. This method return true if the file was successfully written, false otherwise.

<boolean>LoadIconFile <filename>szFilename

This method reads a string from the specified file. If no path is specified in szFilename, the file will be read from the current CUI directory. This method return true if the file was successfully read, false otherwise.

<string>ReadIconFile()

This method returns the string read in the colorMan.LoadIconFile method.

Interface: quadMenuSettings (new methods)

<void>SaveSettingsFile <filename>szFilename

This method saves the current quad menu settings to the specified file. If no path is specified in szFilename, the file will be stored in current CUI directory. This method return true if the file was successfully written, false otherwise.

<void>LoadSettingsFile <filename>szFilename

This method loads the quad menu settings from the specified file. If no path is specified in szFilename, the file will be read from the current CUI directory. This method return true if the file was successfully read, false otherwise.

Interface: gridPrefs (new interface)

This interface exposes properties related to the construction grid.

Properties

.spacing : float : Read|Write

This property exposes the Grid Spacing value. This property corresponds to the Grid Spacing spinner in the Grid and Snap Settings dialog, Home Grid tab

.majorLines : integer : Read|Write

This property exposes the Major Lines value. This property corresponds to the Major Lines every Nth spinner in the Grid and Snap Settings dialog, Home Grid tab

Notes

Setting these properties does not update the Grid and Snap Settings dialog, Home Grid tab displayed values if the dialog is open.

Interface: statusPanel (new interface)

This interface exposes methods for hiding the status panel, and seeing if the status panel is hidden.

<void>setVisible <boolean>visible

If visible is true, the status panel will be set visible. If false, the status panel will be hidden.

<boolean>isVisible()

Returns true if the status panel is visible, false if hidden.


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 is on the left side of the window. It contains four navigational tabs, for Contents, Index, Search, and Favorites.

  • The Topic pane is on the right side of the window. It displays the selected help topic, or the default help topic.

  • The toolbar 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.

  • Right-click the Contents or Favorites tab or the Topic pane for shortcut menu commands.

See also

Finding Information Fast

Searching for Help Topics

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.

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

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 containing any word or phrase.


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 or parentheses 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.

Without the quotation marks, the query is equivalent to specifying "new AND operator," which will find topics containing both of the individual words, instead of the phrase.

Wildcard expressions

esc*
or
80?86

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.

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 the second term. | ole NOT dde | Topics containing the word "OLE," but not the word "DDE."
Both terms in the same topic, close together. | user NEAR kernel | Topics containing the word "user" within eight words of the word "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.

    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.

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 (HTML Help Viewer)

Favorites Tab

Use tools on the Favorites tab to create a set of topics you use often; you can name them as you choose.

Procedures

To create a list of favorite help topics

  1. Locate the help topic you want to make a favorite topic.

  2. Click the Favorites tab, and then click Add.

To return to a favorite topic

  1. Click the Favorites tab.

  2. Choose the topic, and then click Display.

To rename a topic in the Favorites list

  • Choose the topic, and then enter a new name in the Current topic box.

To remove a favorite topic

  • Choose the topic, and then click Remove.


HTML Help Viewer Toolbar

The Help Viewer toolbar contains the following features.

Hide/Show: Click this toggle to hide the Navigation pane when it is displaying, or show it when it's hidden.

Back/Forward: Click to move to the previously viewed topic, or forward to the following previously-viewed topic.

Print: Prints the current topic (if the Topic pane is active). If the table of contents is active on the Navigation pane, you can choose to print the current topic, or the topic and its subtopics. This is a way of printing a collection of topics.

Options menu: Contains the following commands.

Hide/Show Tabs: Same as Hide/Show buttons, above.

Back/Forward: Same as Back/Forward buttons, above.

Home: Displays the main topic of this online system.

Stop: Halts display of a topic.

Refresh: Redraws the Help Viewer display.

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 contents, and then click Print. | Prints the topic.
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, Index, Search, or Favorites 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
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

Favorites Tab

To | Press
Display the Favorites tab. | ALT+I
Add the currently displayed topic to the Favorites list. | ALT+A
Choose a topic in the Favorites list. | ALT+P, and then UP ARROW and DOWN ARROW
Display the selected topic. | ALT+D
Remove the selected topic from the list. | ALT+R

Notes

  • There are also shortcut menu commands 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.


Point3_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, and allows you to set the slave animation controller.

<maxObject>getWireParent <index>index

This method returns a pointer to the i-th dependent parameter parent.

<index>index: The index you wish to retrieve.

<integer>getWireSubnum <index>index

This method returns the i-th dependent parameter subanim num in the animatable.

<index>index: The index of the subanim.

<control>getCoController <index>index

This method returns a pointer to the i-th CoController.

<index>index: The index of the controller.

<string>getExprText <index>index

This method returns the expression string of the i-th wire parameter.

<index>index: The index of the parameter.

<void>setExprText <index>index <string>text

This method allows you to set the expression string of the i-th wire parameter.

<index>index : The index of the parameter

<string>text: The expression you wish to set.

See also Class IbaseWireControl, in the SDK Help file accompanying this product.


Portable License Manager

See maxOps