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.

A

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.

B

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.

C

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.

D

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.

E

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.

F

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.

G

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.

H

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.

K

keyboard.shiftPressed

keyboard.controlPressed

keyboard.altPressed

keyboard.escPressed

These variables access the current state of the keyboard shift, control, alt and escape 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.

L

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.

M

macroRecorder

Read only system global - macro recorder edit window <WindowStream> value

manipulateMode

Get/set the 3ds Max manipulate mode. When true, manipulate mode is active.

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.

maxOps.productAppID : enum : Read

productAppID enums: {#none|#max|#viz|#gmax}

The enum values returned are as follows:

#none - no ID

#max - 3ds Max

#viz - Autodesk VIZ

#gmax - gmax

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.

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.

N

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.

Note:

The subObjectLevel and numSubObjectLevels system global variables return values other than 'undefined' if you are in the Motion panel. At the top of the Motion panel there is a Selection Level/Sub-Object drop-down list. This is for Trajectory mode, and switches you in and out of Keys SO mode. Because of this, the test (subobjectlevel != undefined) is not a valid test of whether you are in the Modify panel. Instead, use the test (getCommandPanelTaskMode() == #modify).

O

 

P

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

A PRS animation controllers message notification system optimization was introduced in 3ds Max 6 and was enabled by default. It speeds up complex rigs using multiple animation controllers. When set to true, the optimization is enabled and no redundant notifications are sent by the controllers. When set to false, the animation system behaves as in 3ds Max 5 and earlier.

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

An optimization was introduced in 3ds Max 7 that checks to see if a node has already been invalidated before sending out notifications to it's dependents that it has been changed. It speeds up complex rigs, especially those that involve the new expose transform helper. When set to true, the optimization is enabled and multiple notifications will not be sent out. When set to false, the animation system behaves as in 3ds Max 6 and earlier. It is true by default.

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

This integer value defines the number of decimal digits displayed by spinners.Corresponds to the Precision value in the Spinners group in Customize > Preferences > General.

preferences.spinnerSnap

This float value defines the spinner snap value. Corresponds to the Snap value in the Spinners group in Customize > Preferences > General.

preferences.useSpinnerSnap

This Boolean value defines whether to use the spinner snap. Corresponds to the Use Snap checkbox in the Spinners group in Customize > Preferences > General.

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.

Q

 

R

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

deleted_feature.gif In versions prior 3ds Max 6, this global variable was used to get and set the renderer type (#production or #draft). The #draft renderer option has been removed from 3ds Max 6, making this variable obsolete. It only accepts and returns #production now and is kept for backwards compatibility of scripts from earlier versions that might be checking this value.

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.

rendSimplifyAreaLights

When set to true, area lights will be examined and converted to point light sources when appropriate.

Note

There is also an equaly-named parameter to the render() command to achieve this behavior.

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.

S

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

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

Note:

The subObjectLevel and numSubObjectLevels system global variables return values other than 'undefined' if you are in the Motion panel. At the top of the Motion panel, there is a Selection Level/Sub-Object drop-down. This is for Trajectory mode, and switches you in and out of Keys SO mode.

Because of this, the test (subobjectlevel != undefined) is not a valid test of whether you are in the Modify panel. Instead, use the test (getCommandPanelTaskMode() == #modify).

sysInfo.DesktopSize

A read only variable to get the desktop size in pixels as a <point2> value. See also System Information and getMAXWindowSize() under Miscellaneous Functions

sysInfo.DesktopBPP

A read only variable to get the desktop color depth in bits per pixel as an <integer> value. See also System Information

sysInfo.MAXPriority

Get/set the 3ds Max process priority as a <name> value. Valid priority values are #high, #normal, and #low. See also System Information

T

ticksPerFrame

Lets you get and set an Integer value defining the system time resolution. There are always 4800 ticks per second, this means that ticksPerFrame is dependent on the frames per second rate
(ticksPerFrame * frameRate == 4800)

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

Lets you get and set the viewport playback speed mode. See Time Configuration Dialog.

timeConfiguration.PlaybackLoop

Get/set whether to loop the viewport playback. Only used when timeConfiguration.realTimePlayback is set to true. See Time Configuration Dialog. Available in 3ds Max 8 and higher.

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.

toolMode.coordSysNode

A read/write variable containing a node value or undefined. This variable reflects which node, if any, is the current reference coordinate system node. Assignment to this variable must be a node value.

trackbar.filter

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

U

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:

#Inches

#Feet

#Miles

#Millimeters

#Centimeters

#Meters

#Kilometers

units.SystemScale

Get/set the current system unit scale value as a <float>. This is the value shown in Customize Units Setup... > System Units Setup > System Units Scale group.

units.SystemType

Get/set the current system unit scale type as a <name>. This is the unit shown in Customize > Units Setup... > System Units Setup > System Units 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.

V

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

Scanline Renderer Specific System Global Variables

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*"

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.