MAXScript Language Improvements in 3ds Max 9

The following is a description of internal changes and "tweaks" to the MAXScript language in 3ds Max 9. Other than the "What is new..." topic, these changes do not implement new objects, classes, methods or interfaces, but change the way MAXScript works internally. Usually these changes either improve performance or simplify programming.

64 bit Values and Operations

64 Bit Values - Double, Integer64, IntegerPtr

new.gif Three new Number value classes have been added to MAXScript: Double, Integer64 and IntegerPtr. They support all operations operating on Float and Integer values documented in the Number Values topic.

is64bitApplication Method

new.gif A new method has been added to MAXScript to determine whether it is running in a 32 bit or a 64 bit build.

Bit Methods For Double and Integer64 Conversion

new.gif Two new methods have been added to the bit struct in MAXScript to convert explicitly between Double and Integer64 values: bit.doubleAsInt64() and bit.int64AsDouble().

DotNet Controls, Classes, Objects and Methods

DotNet In MAXScript

new.gif Not all ActiveX controls have been compiled for the 64 bit versions of Microsoft Windows. Various areas of the 3ds Max User Interface rely on ActiveX controls like TreeView and ListView. To provide an alternative implementation of these and other controls, 3ds Max 9 adds access to DotNet Classes, Objects, Methods and Controls. These can be used in both 32-bit and 64-bit builds of 3ds Max.

MAXScript Editor Options

The MAXScript Editor Windows

new.gif The new system global variable editorShowPath controls whether the MAXScript Editor will display the full path of the edited script (true, default in 3ds Max 9), or only the file name (false, the only mode prior to 3ds Max 9) in the title bar. Changing the value will update the open MAXScript editor windows.

new.gif When doing an Open or Save As from an editor window, and there is a filename associated with the editor window, the file open/save dialog will open to the filename's path. When doing an Open, Save, or Save As from an editor window without a filename, or from Listener or the main max window, the last directory specified in a MAXScript script file open/save dialog will be used (unless the user cancelled out of the dialog).

MAXScript Source Filename and File Offset Access

MAXScript Source Filename Access

new.gif A new method was added to allow MAXScript code to query the source file is has been run from: getSourceFileName().

new.gif The new method getSourceFileOffSet() returns the character position in the source script file, 'undefined' if not called from a source script file.

Escape Behavior

Aborting Execution with the ESC Key

new.gif The system global variable escapeEnable has been changed to default to false. It used to default to true in versions prior to 3ds Max 9.

Deep Copy Arrays

Array Values

new.gif New method deepCopy() has been implemented for Array Values. It creates a copy of the array including copies of all its elements and supports nested arrays.

Formatted Print

FormattedPrint

new.gif A new method introduced in 3ds Max 9, previously available in the Avguard DLX Extensions, which can be used to control the format of numerical values.

Heap and Memory Management

Memory Allocation and Garbage Collection

new.gif The HeapSize and the HeapFree MAXScript System Global variables have been changed from Integer to Integer64 to accommodate the increased memory address space of 64 bit systems.

new.gif The initial heap size is now limited to 512MB. If the initial heap size is still too high, and the specified memory block cannot be allocated, the initial heap size is recursively decreased by 10% until the memory block can be allocated. If a 1MB memory block cannot be allocated, an assert is triggered and the 3ds Max session is terminated (if the system cannot allocate 1MB at startup, something is very wrong). Otherwise, a message is displayed in the status panel stating that the requested heap size was automatically decreased, and gives the actual heap size allocated.

A test was added to ensure that the initial heap size is at least the absolute minumum required by MXS - 12 bytes.

Code was added so that as new values are allocated, the heap size is automatically increased if necessary (requested memory size not available in the heap after performing a full garbage collection) . The first attempted increase is the maximum of 50* the requested size or 512KB. If this allocation fails, a series of allocation attempts is made with decreasing allocation sizes, with the last one being the maximum of the requested size or 256KB. If this final allocation attempt fails, a runtime error is thrown. Otherwise, a message is displayed in the status panel stating that the requested heap size was automatically increased, and gives the new heap size.

new.gif A new heapCheck() method added to MAXScript. This method is for internal debugging. It can be called by tools to perform a minimal consistency check of the Heap.

MAXScript System Globals

new.gif The MAXScript stack size was increased from 1024000 to 2048000 bytes. The MAXScript System Global variable stackSize will now return the new size, but the stack size cannot be effectively changed - setting the variable to higher values will do nothing.

User Interface Controls

new.gif A new .tooltip property has been added to Button, Checkbutton, Mapbutton, Materialbutton and Pickbutton UI controls. The property can now be both get and set via MAXScript. In version prior to 3ds Max 9, tooltip: was only a construction parameter.

Create Panel

Create Panel

new.gif The previously undocumented method isCreatingObject() returns true if any object is being created in the Create panel when called without arguments. Previously, it required exactly one parameter.

Callbacks

new.gif New callbacks related to Named Selection Sets were added to the General Event Callbacks Mechanism, in a new Named Selection Sets Notifications section.

#NamedSelSetCreated, calling callbacks.notificationParam() returns the new name

#NamedSelSetDeleted, calling callbacks.notificationParam() returns the name of the deleted selections set.

#NamedSelSetRenamed, calling callbacks.notificationParam() returns an array containing the old name and new name.

new.gif New callback related to Modify Panel Sub-Object Level was added to the General Event Callbacks Mechanism in the existing Modifier Panel Notifications section.

#ModPanelSubObjectLevelChanged, calling callbacks.notificationParam() returns an array containing the new SO level number and the old SO level number.

new.gif New callbacks related to resetting the Direct3D device (for example when switching between 3ds Max and other applications, screensavers etc.) were added to the General Event Callbacks Mechanism in the newDirect3D Notifications section.

#D3DPreDeviceReset

#D3DPostDeviceReset

MAXScript Debugger

Interface: MXSDebugger

new.gif An option was added to the MAXScript Debugger to clear the output message window when a break occurs.

The option was added in the MAXScript options dialog as a simple checkbox, is saved / loaded in the INI file and is also exposed via the MXSDebugger interface.

Previously when using the Debugger, any output that was already in the output message window was retained when a new break occured. Thus when a new stack dump was put into the output window, it could become confusing to users, where the new dump started, and where the old dump ended. This fix simply clears the output window, and scrolls to the top of the output window.

new.gif A horizontal line above each stack level dump was added to the output formatting during a Debugger stack dump to help seperate the different stack levels.

Icon Bitmaps

New Colorman Interface Methods

new.gif The following methods were added to the Colorman Interface: colorman.reInitIcons() and colorman.resolveIconFolder(). These methods can be used to reload add icon files and to resolve a file name using the icon paths.

Creating Icon Bitmap Files

new.gif CUI icon files (*_16i.bmp, *_16a.bmp, *_24i.bmp, *_24a.bmp) are loaded first from the user icon directory, then the max system icon directory, and then <3dsmax.exe>\ui\icons. If a file set is present in multiple directories, the version in the first directory is used.

new.gif The icon filename specified as an argument to loadPicture, the filename in images arrays for UI items, and the filename for the bitmap UI item no longer needs to specify a path to the icon folder. The icon filename will be searched for in the multiple directories - see above link for details.

Materials and Material Libraries

new.gif Two new methods added to allow the loading and saving of a material library as a temporary (as opposed to current) library - loadTempMaterialLibrary() and saveTempMaterialLibrary()

new.gif The method loadMaterialLibrary() was fixed to also search the material library path.

new.gif Wrapping of MtlBaseLib instances was not occurring properly.

refs.dependents a[1]

#(#materialLibrary())

--previously would return something like:

RefTarg:MtlBaseLib

New User Directories For "Least Privileged" Access

new.gif The new userMacroScripts system path becomes a second macroscript load location. Duplicate scripts found in this location take precedence over those found in exe\macroscript. Additional details:

The user Macros directory can be set to the max macros directory to retain existing behavior.

new.gif The new userStartupScripts is a user location for placing scripts that are run at startup.

new.gif The new temp system directory provides a safe location to write a temporary file. No special cleanup is done for this directory, this variable is only provided to avoid ambiguity with regards to where a client should write a temp file. Previously, plugins could write to anywhere, including the max root, C:\temp, or a location specified by the TMP environment variable. Most of these locations (except perhaps the last) would be invalid under Vista. The temp directory will directed to a safe-write location.

Folder Search Order

Startup Scripts

new.gif Startup scripts in the 3ds Max system startup scripts directory are run first, and then the Startup scripts in the user startup scripts directory are run, providing that the user startup scripts directory is different than the max system startup scripts directory. The startup.ms file is searched for in the following order:

new.gif The filename specified as an argument to openFile(), encryptScript(), include() and editScript() will now also be searched for in the user scripts directory.

Symbolic Pathnames

Symbolic Pathnames

new.gif The following new symbolic pathnames have been added to MAXScript:

 $exports

 $help

 $expressions

 $previews

 $maxstart

 $vpost

 $drivers

 $autoback

 $marketDefaults

 $icons

 $renderOutput

 $animation

 $archives

 $photometrics

 $renderAssets

 $userScripts

 $userMacros

 $userStartupScripts

 $userIcons

 $maxData

 $maxSysIcons

new.gif The $maps and $plugins symbolic pathnames can now also specify an index, and the indexed directory will be used.

For example:

"$maps[2]\\mybitmap.tga"

 

SymbolicPaths Struct

new.gif The new symbolicPaths Struct exposes advanced methods for accessing system symbolic paths and managing user-defined symbolic paths.

Compare Bitmaps

compareBitmaps() method

new.gif The new compareBitmaps() method returns true if the two bitmaps provided as arguments compare as the same, false if not.

Misc. Fixes

new.gif Exception reports which had the word '+ve' instead of 'positive' since 3ds Max R2 have been fixed.

new.gif The out-of range error message for Function Published Interfaces range checking was changed from:

-- Runtime error: Parameter value out of range: 100

to:

-- Runtime error: Parameter value out of range: < 1 or > 99: 100

new.gif The MAXScript inspection methods have been modified to return 'printable' names - these are names with punctuation replaced with '_'. Accessor methods have been modified to also test against the printable names. Existing scripts will still run, as the "raw" names are tested for resolution first, then the printable names.

Methods changes from const Primitive to const Generic:

new.gif The following methods now inherit from the const Generic instead of const Primitive. acos(), asin(), atan(), atan2(), ceil(), cos(), cosh(), floor(), getInterface(), getInterfaces(), log(), log10(), mod(), pow(), showMethods(), sin(), sinh(), sqrt(), tan(), tanh().

This change was made for internal SDK organization reasons and should have no influence in performance or functionality.

See also

What is New in MAXScript in 3ds Max 9

Documentation Changes in 3ds Max 9

New in MAXScript