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
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.
A new method has been added to MAXScript to determine whether it is running in a 32 bit or a 64 bit build.
BitMethodsFor Double and Integer64Conversion
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
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 newsy stem 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.
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
A new method was added to allow MAXScript code to query the source file is has been run from: getSourceFileName().
The new method getSourceFileOffSet() returnsthecharacter position in the source script file, 'undefined' if not called from a source script file.
Escape Behavior
Aborting Execution with the ESC Key
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
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
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
The HeapSize and the HeapFree MAXScript System Global variables have been changed from Integer to Integer64 to accommodate the increased memory address space of 64bit systems.
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.
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.
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
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
The previously undocumented method is CreatingObject() returns true if any object is being created in the Create panel when called without arguments. Previously, it required exactly one parameter.
Callbacks
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 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 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 new Direct3D Notifications section.
#D3DPreDeviceReset
#D3DPostDeviceReset
MAXScript Debugger
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.
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
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.
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.
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
Two new methodsadded to allow the loading and saving of a material library as a temporary (as opposed to current) library - loadTempMaterialLibrary() and saveTempMaterialLibrary()
The method loadMaterialLibrary() was fixed to also search the material library path.
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
The new userMacroScripts system pathbecomes a second macroscript load location. Duplicate scripts found in this location take precedence over those found in exe\macroscript.Additional details:
-
Macroscript files auto-generated from MAXScript files are placed in this folder.
-
Macroscript files auto-generated from dragging script text to a toolbar will be placed in this folder.
-
If a user right-clicks to Edit the Macroscript, and the macroscript was in the default macroscript directory, the script editor filename will be changed to point the file to the userMacroscripts directory. A dialog will be displayed warning that the script editor filename path was changed. If the userMacroscripts and max system macroscript directory are the same, no dialog will be displayed.
The user Macros directory can be set to the max macros directory to retain existing behavior.
The new userStartupScripts is a user location for placing scripts that are run at startup.
The new tempsystem 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 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:
-
The user scripts directory
-
The user startup scripts directory
-
The max system scripts directory
-
The max system startup scripts directory
-
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
The filename specified as an argument to openFile(), encryptScript(), include() and editScript() will now also besearched for in the user scripts directory.
Symbolic Pathnames
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 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"
The new symbolicPaths Struct exposes advanced methods for accessing system symbolic paths and managing user-defined symbolic paths.
Compare Bitmaps
The new compareBitmaps() method returns true if the two bitmaps provided as arguments compare as the same, false if not.
Misc. Fixes
Exception reports which had the word '+ve' instead of 'positive' since 3ds Max R2 have been fixed.
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
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 wills till run, as the "raw" names are tested for resolution first, then the printable names.
Methods changes from const Primitive to const Generic:
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.