X

MAXScript

(Redirected from Maxscript)

This page will link you to useful functions and practices regarding MAXScript.

MAXScript is the scripting language of 3ds Max.

It is possible to edit MAXScripts using the built-in MAXScript Editor or alternatively using external text editors. MAXScript allows an arbitrary number of Editor windows to be opened at any given time. To open a script for editing, go to Main Menu > MAXScript > Open Script...

To evaluate a script, either use Main Menu > MAXScript > Run Script..., open the script in an Editor window and press Ctrl+E (or go to Menu>File>Evaluate All), or drag the script from Windows Explorer to the 3ds Max toolbar.

Single line expressions can be entered either in the Mini-Listener located in the bottom left corner of the 3ds Max UI starting with Release 3, or in the MAXScript Listener. The Listener can be opened by either pressing F11, right-clicking the Mini-Listener > Open Listener Window, by going to Main Menu > MAXScript > MAXScript Listener or by going to Utilities tab > MAXScript > Open Listener.

MAXScript provides a MacroRecorder which can generate code automatically based on user interactions with the UI. Selected code can be dragged from the top (pink) area of the MAXScript Listener onto a toolbar to create a new button with this functionality.


Contents

Development History

The predecessor of 3D Studio MAX - Autodesk 3D Studio (DOS) introduced an animation-only scripting language in Release 4 which was licenses from a 3rd party developer. The same developer provided a full set of scripting tools for the other modules of 3D Studio DOS, but these were never licensed by Autodesk. At the time R4 shipped, 3D Studio MAX was already under (top secret) development, but its first release in 1996 did not provide a scripting language at all. The closest thing to scripting Release 1 had was the Expression controller which provided a limited set of mathematical functions and branching statements to create procedural animations.

  • In 1996, a 3rd party developer - John Wainwright of Lyric Media - started a Beta program for a scripting plug-in for 3D Studio MAX R1 called MAXScript.
  • On August 4th 1997, Kinetix announced at Siggraph in Los Angeles that one of the major additions to the upcoming 3D Studio MAX R2 would be MAXScript. John Wainwright was hired as a full-time developer to work on further developing the language and integrating it closer to the software's core. The initial version of MAXScript was implemented as a Utility. Utilities are the lowest form of plug-ins for 3ds Max - they can have full access to all scene data, but other than most other plug-in classes they don't become an integral part of the system and cannot be accessed by other plug-ins. The MAXScript Reference including some basic tutorials was written by John Wainwright himself.
  • 3D Studio MAX R3 was largely refactored to integrate MAXScript into the core system. Most procedural plug-in classes were rewritten to support a new ParameterBlock2 (the data container responsible for storing and managing object data) which allowed objects to emit MAXScript code in a MacroRecorder. The program's GUI was also rewritten to allow scripts created using the MacroRecorder or generated manually to be placed on toolbars. The other very big addition to MAXScript was the ability to create scripted plug-ins like procedural geometry primitives, gizmo-based deformation modifiers, extended material and maps etc. The MAXScript reference was edited by Larry Minton who emerged as a MAXScript guru on the Kinetix' MAXScript Support Forum and was hired by the company to take over the documentation.
  • The newly rebranded Discreet 3dsmax 4 introduced another large change in the language - up until this version, methods and properties of any objects had to be exposed explicitly which required large efforts and human resources. Release 4 implemented a Function Publishing Interface system which allowed developers to expose their new plug-ins to MAXScript almost automatically. The application's GUI was once again refactored to accept a single object type called an ActionItem in all its areas including Toolbars, Menus, the new right-click QuadMenus and as Keyboard Shortcuts. This allows developers to create MacroScripts and let the end user decide where to place and how to access these scripts. Yet another advancement in this version was the support for ActiveX controls in scripted User Interfaces. After this release John Wainwright decided to leave Discreet and handed development over to Larry Minton who worked as MAXScript Quality Engineer for that release. The MAXScript Reference was edited by Mason Foster.
  • Versions 5 to 7 improved on top of the existing language without significant architectural changes. Starting with 3dsmax 5, the MAXScript Reference was edited by Borislav 'Bobo' Petrov and included additional tutorials, FAQs, illustrations and sample code in each update.
  • Version 8 introduced an initial version of a MAXScript Debugger.
  • Version 9 introduced support for .NET classes, objects and controls, allowing MAXScript to make use of external assemblies and reuse code written for other applications as well as place .NET forms in MAXScript UIs or design .NET User Interfaces.
  • Version 2008 replaced the multiple MAXScript Editors based on the Microsoft RichEdit control with a single multi-document editor based on the Scintilla Open Source control and a modified version of the SciTE Editor. In addition, the complete Avguard MAXScript Extension developed by Larry Minton as a free plug-in has been integrated into the core package.

MAXScript Language Overview

The MAXScript language was developed to be used by artists as well as by Technical Directors and programmers. It provides relatively relaxed syntax rules and is more similar to BASIC than to C++ or Unix command line as is the case with Maya's MEL script. The internal structure of MAXScript has more similarities to LISP - MAXScript is an expression-based language.

Some notes on syntax specifics:

  • Semi-colons (;) are not required for end of line termination but are allowed. They are only required to delimit multiple expressions in the same line:
      a = 10
      print a
      --is the same as
      a = 10;
      print a;
      --which is the same as
      a = 10; print a;
  • The language is completely CASE-INsensitive, i.e. a variable called maxSCRIPT is the same as MAXScript. The only exception is comparison of string values which is case sensitive. MAXScript provides a special name value which is case-insensitive and is usually employed for passing enums and other similar parameters instead of strings. Also, a matchPattern method allows the string comparison in both case-sensitive and case-insensitive manner:
      "Bobo" == "bobo"
      -->false
      "Bobo" as name == "bobo" as name
      -->true
      #Bobo == #bobo  --# denotes a name value
      -->true
      matchPattern "Bobo" pattern:"bobo"
      -->true
      matchPattern "Bobo" pattern:"bobo" ignorecase:false
      -->false
  • Variables do not require explicit type declaration or value assignment. Uninitialized variables always return a special value 'undefined' which is equivalent to NULL. The type of the variable depends on the type of the value stored in it and can change dynamically, for example a=10 makes 'a' an integer, a="b" right after that will turn the variable 'a' into a string variable.
  • Round brackets (parentheses) are used to define code blocks and name spaces.
  • Arrays are defined using #() and have no fixed element type - an array can contain any number of different elements with different classes, including other arrays.
  • Braces {} are only used as part of a bitArray value definition #{}. BitArrays are a compact list containing only on/off bits (true or false values) and are used to store indexed selections like vertex and face selection lists.
  • Rectangular brackets [] are used for indexed or by-name access to sub-objects and array elements.
       aBox = box() --create a box
       --> $Box:Box01 @ [0.000000,0.000000,0.000000]
       aBox[3] --access 3rd sub-anim track
       --> SubAnim:Transform
       aBox[#Transform] --get the same track using by-name access:
       --> SubAnim:Transform
       aBox[3][1] --get the first sub-anim of the transform track
       --> SubAnim:Position
       aBox[3][1][2] --get the second sub-anim of the position track
       --> SubAnim:Y_Position
       someArray = #(1,2,5,6,"Bobo") --define an array
       --> #(1,2,5,6,"Bobo") 
       someArray[4] --get the 4th element
       --> 6
       someArray[7] --get the 7th element
       --> "Bobo"
       someArray[8] --get the 8th element - it does not exist
       --> undefined
       
  • Single-line remarks are inserted using double-dash --. Multi-line remarks are inserted using slash-star and star-slash pairs like /* some remark here */
  • Scene nodes (a.k.a. scene objects) can be accessed by prefixing their name with a Dollar sign $. For example $Box01 denotes a box named "Box01". The same syntax can be used to access multiple objects with similar names using wildcards, for example $Box* means all objects whose name starts with "Box" like "Box01", "Box02", "Boxer" etc.
  • Properties of objects are accessed either using a DOT notation (Object.PropertyName) or via GetProperty / SetProperty method calls. To list available properties, for example of an existing box called "Box01", use
      showProperties $Box01
      --or the shorthand form 
      show $Box01
      --To get an array of all properties as names, use
      theProperties = getPropNames $Box01
  • Some MAXScript methods as well as user-defined functions are implemented as Mapped (or Mappable) which means that they can accept both a single object or a collection of many objects as an argument. In the latter case, the function iterates through all objects using an internal loop. Property assignments are also mappable, for example $Box*.height = 10 will assign 10 to all objects whose name starts with "Box". Mapped functions are marked as such in the MAXScript Reference.

Application Areas

MAXScript is very versatile - the number of areas it can be used is limited mainly by the imagination of the user. Nevertheless, there are certain fields MAXScript excels and is used more often in:

Command Line Application Control

MAXScript can be used to access different aspects of the 3D scene and 3ds Max in general and change properties, create, modify and delete objects, iterate through group of objects and filter out by various criteria, even change some settings that are not exposed to the User Interface and are accessible only through MAXScript (for example experimental features or system switches). The command line interface (the Listener and Mini-Listener) can also be used to perform quick mathematical calculations or print statistical data about the current scene and so on.

User Interface creation

MAXScript provides a set of User Interface controls which can be placed in Rollouts to be displayed as Dialogs, in Rollout Floaters, in the Command Panel (as part of scripted Utilities, scripted plug-ins and Custom Attributes), in the Material Editor (as part of scripted material and map plug-ins) and in the Render Effects tab of the Render Dialog (as part of scripted Render Effects).

The UI controls include button, checkbutton, pickbutton, mapbutton, materialbutton, imagebutton, spinner, slider, checkbox, radiobutton, dropdownlist, listbox, multilistbox, combobox, bitmap, colorpicker, curvecontrol, edittext, groupbox, label, hyperlink, imgtag, popupmenu, progressbar, subrollout and timer.

User Interface controls can be ordered automatically, relatively and absolutely.

  • Automatic placement is the default behavior: Simply listing controls one after the other will order them automatically using the default alignment settings and will also set the dimensions based on the caption text and size of the parent rollout. The formatting settings can also be specified by the user, including across:, align:, height:, width: and fieldwidth:.
  • Relative placement can be performed on top of the automatic ordering using the offset:[X,Y] parameter which will shift the control relative to its automatic location.
  • Absolute placement can be performed using the pos:[X,Y] parameter which specifies the absolute position of the upper left corner of the control relatively to the upper left corner of the parent rollout.

In addition, ActiveX controls and (since 3ds Max 9) .NET controls can be integrated with scripted rollouts. In the case of .NET, UIs based completely on Windows Forms can be created inside of MAXScript.

MAXScript provides a utility called Visual MAXScript which allows the visual design of rollouts in a drag&drop manner similar to MS Visual Studio. The controls created using Visual MAXScript will always use absolute placement.

MacroScripts

MacroScripts were initially introduced in R3 as a form of package for code emitted by the MacroRecorder, but have become the preferred form of scripted tools because they can be placed on Toolbars, Menus, QuadMenus, or assigned to Shortcuts.

Simple MacroScripts have a simple form of a body containing some code to be executed when the button/menu item/shortcut is activated.

MacroScripts can include their own GUI or execute commands directly when launched.

MacroScripts have an optional complex form with a number of event handlers that can be used to add context sensitivity to the code and control the button/menu item's visibility, active and checked state and even provide an alternative action when used as menu item.

MacroScript can also be made droppable using a special event handler which can detect whether a script has been dropped into the viewport or onto objects and perform operations on them.

Scripted Functions

MAXScript can be used to create global functions that can be accessed by other scripts or via the command line of the Listener. The source files of these functions can be installed in any folder listed in the Plugin paths or in the dedicated stdplugs/stdscripts and scripts/startup folders. Functions can also be combined into a set using a scripted struct to provide better code packaging and reduce clutter in the global name space (scope) of MAXScript.

Callback Functions

Scripted callback functions can be registered with the system and are triggered by system events like the opening of a scene, the creation, modification or deletion of an object, the launching of the renderer and so on. These scripted functions can be used to monitor the user's actions and make changes in the background when necessary; test files, objects and other settings for correctness (sanity checks); modify objects on the fly (for example assign a material to any newly created object, adjust settings to some user defaults when modifiers are added and so on) and so on. A couple more specialized callback mechanisms are available in MAXScript to trigger user function calls on Time Slider changes, viewport redraws or various operations on specified objects incl. topology, transformations, sub-animation structure and more.

Scripted Plug-ins and Custom Attributes

Scripted Plug-ins were introduced in R3 and allow fast prototyping of several classes and levels of plug-ins to extend 3ds Max without using the SDK. The following scripted plug-in classes are currently supported:

  • Atmospheric (extend existing only)
  • Camera (extend existing only)
  • Geometry
  • Helper (extend existing only)
  • Light (extend existing only)
  • Manipulator
  • Material (extend existing only)
  • TextrureMap (extend existing only)
  • Modifier (extend existing only)
  • SimpleMod
  • RenderEffect
  • Shape (extend existing only)

While usually a lot slower to execute than C++ plug-ins developed using the SDK, scripted plug-ins are orders of magnitude faster to develop and can often solve a problem as effectively as a regular plug-in.

A special case of scripted plug-ins are the so-called Custom Attributes (a.k.a. Parameters) - they are implemented as user-defined scripted parameter blocks with optional UI controls which can be attached to most scene objects including base objects, modifiers, materials, maps, controllers etc.

Integration

MAXscript and Python

MAXScript and Python

MAXscript and .NET

MAXScript and .NET

Math

Geometric Calculations

External Links

Scriptspot - Arguably the largest repositry of maxscripts online

Virtual Republic Boboland - Home of Borislav "Bobo" Petrov

MEL To MAXScript - A basic comparison of MEL and MAXScript syntax and functionality for users for Maya and 3ds Max.

This Article is a Stub - You can help CGSociety Wiki by expanding it.




The Society

The CGSociety is the most respected and accessible global organization for creative digital artists. The CGS supports artists at every level by offering a range of services to connect, inform, educate and promote digital artists worldwide

Contact | Privacy | Advertising | About CGS