Pipeline Integration Support

This topic describes the features that let you customize the deployment and execution of 3ds Max for better integration into production pipelines.

A well defined production workflow, or "pipeline", helps processes flow efficiently on large or complex projects involving multiple steps executed by different teams using hardware and software configurations specific to those steps.

Flexible and customizable tools that can be reconfigured to new requirements driven by the specific of the production are key to building production pipelines.

3ds Max's support for scripting through Maxscript and Python, customization of virtually all its aspects through user defined startup scripts, a rich set of command line parameters, batch and command line rendering modes, make it easy to integrate it into production pipelines.

In 3ds Max 2022.3, these pipeline integration capabilities are enhanced to make it even easier for studios to configure the software so artists can seamlessly switch between tasks that require uniquely configured environments including project settings, user preferences, and script and plug-ins. We achieved this through exposing multiple environment variables to control all aspects of the environment (location of projects, user settings, scripts and assets), and by adding support for embedding environment variable tokens into file and folder paths stored in configuration files used by 3ds Max.

Customization through Environment Variables

The paths to user data, user scripts, plugins, file-based assets such as maps and xrefs, and projects represents the 3ds Max user environment. The sections below describe how to customize and extend them, when supported, using environment variables. See the Environment Variables topic for a list of all system Environment Variables used by 3ds Max.

The environment variables described below are best used for customizing the environment of a 3ds Max process, regardless of its version. For example, two or more 3dsmax.exe processes launched from the same installation can have different environments. If the environment variables are set at a user or system level, they will affect all 3ds Max versions installed and executed by that user or on that computer.

Note: Although several of the paths representing the user environment can be accessed through the user interface, scripting or SDK, the value of the environment variables described below cannot be modified through those means.

User Data Folder

When the ADSK_3DSMAX_APPDATA_DIR environment variable is defined, 3ds Max uses its value as the location for local user data. By default, user data is stored in C:\Users\<username>\AppData\Local\Autodesk\3dsMax\<year> - 64bit\<lang>. In Maxscript and Python the $maxData symbolic pathname represents this location.

This environment variable allows for defining one path only. It must be a valid path. In case the path is not valid, 3ds Max fails to start with a -10 exit code. If the path is valid but does not exist, 3ds Max creates it. Multiple simultaneous 3ds Max sessions can run with different values of this environment variable.

In order for this environment variable to take effect, 3ds Max must run with User Profiles turned on. When the <3dsMaxInstall>\InstallSettings.ini file contains the data below, it will use User Profiles if enabled in Windows.

[Least User Privilege]
useUserProfiles=1

User Settings Folder

The concept of a User Settings location as was introduced in 3ds Max 2020.

When the ADSK_3DSMAX_USERSETTINGS_DIR environment variable is defined, 3ds Max uses its value as the folder for user settings. By default, user settings are stored in C:\Users\<username>\Autodesk\3ds Max <year>\User Settings. In Maxscript and Python the $userSettings symbolic pathname represents this location.

Note that not all user settings are currently stored at the User Settings location. As of 3ds Max 2022, most of the user settings are still stored in the user data folder.

This environment variable allows for defining one path only. It must be a valid path. In case the path is not valid, 3ds Max fails to start with exit code -10. If the path is valid but does not exist, 3ds Max creates it. Multiple simultaneous 3ds Max sessions can run with different values of this environment variable.

The user settings folder is set during the startup of 3ds Max in the following order of precedence:

Startup scripts (overwrites the environment variable setting)
ADSK_3DSMAX_USERSETTINGS_DIR environment variable (overwrites the 3dsmax.ini setting)
The User Settings value in 3dsmax.ini

If none of the above methods supplies a user settings folder, 3ds Max reverts to the default user settings folder.

User Tools Folder

When the ADSK_3DSMAX_USERTOOLS_DIR environment variable is defined, 3ds Max uses its value as the folder for user tools (such as Scene Converter scripts and Max Creation Graph compounds). By default, user tools are stored in C:\Users\<username>\Autodesk\3ds Max <year>\User Tools. In Maxscript and Python the $userTools symbolic pathname represents this location.

The user tools folder is set during the startup of 3ds Max in the following order of precedence:

Startup scripts (overwrites the environment variable setting)
ADSK_3DSMAX_USERTOOLS_DIR environment variable (overwrites the 3dsmax.ini setting)
The User Tools value in 3dsmax.ini

If none of the above methods supplies a user tools folder, 3ds Max reverts to the default user tools folder.

Project Folder

The concept of a project folder was introduced in 3ds Max 2020. For more information see the Project topic.

When the ADSK_3DSMAX_PROJECT_FOLDER_DIR environment variable is defined, and 3ds Max is started with a new scene, it uses the value of this environment variable to store project data, such as material libraries, render presets, render output, autobackup file location, and so on.

By default the project configuration is located at C:\Users\<username>\Documents\3ds Max <year>. Project folder customization is exposed to Maxscript and Python through the pathConfig structure's methods, such as pathConfig.setCurrentProjectFolder <path>.

This environment variable allows for defining one path only. It must be a valid path. In case the path is not valid, 3ds Max fails to start with a -10 exit code. If the path is valid and does not exist, 3ds Max creates it. Multiple simultaneous 3ds Max sessions can run with different values of this environment variable.

The project folder is set during the startup of 3ds Max in the following order of precedence:

Startup scripts (overwrites the environment variable setting)
ADSK_3DSMAX_PROJECT_FOLDER_DIR environment variable (overwrites the 3dsmax.ini setting)
The ProjectFolder value in 3dsmax.ini

If none of the above methods supplies a project folder, 3ds Max reverts to the default project folder.

User Startup Scripts Folders

An environment variable named ADSK_3DSMAX_STARTUPSCRIPTS_ADDON_DIR allows for defining a list of semicolon delimited paths, which are used by 3ds Max to search for user defined startup scripts in addition to the startup script folder defined through the Configure User and System Paths dialog.

By default, user startup scripts are stored in C:\Users\<username>\AppData\Local\Autodesk\3dsMax\<year> - 64bit\<language>\scripts\startup. In Maxscript and Python the $userStartupScripts symbolic pathname represents this location.

The paths specified through this environment variable are searched after the user defined startup scripts location. Multiple simultaneous 3ds Max sessions can execute with different values of this environment variable. If any of the paths defined through this environment variable are incorrect, an error is logged to the system log (Max.log).

User Scripts Folders

An environment variable named ADSK_3DSMAX_SCRIPTS_ADDON_DIR allows for defining a list of semicolon delimited paths which are used by 3ds Max to search for user scripts in addition to the user script folder defined through the Configure User and System Paths dialog. By default, user scripts are stored in C:\Users\<username>\AppData\Local\Autodesk\3dsMax\<year> - 64bit\<language>\scripts\. In Maxscript and Python the $userScripts symbolic pathname represents this location.

The paths specified through this environment variable are searched after the user defined scripts location. Multiple simultaneous 3ds Max sessions can execute with different values of the environment variable. If any of the paths defined through this environment variable is incorrect, an error is logged to the system log (Max.log).

User Macro Scripts Folders

An environment variable named ADSK_3DSMAX_MACROS_ADDON_DIR allows for defining a list of semicolon delimited paths which are used by 3ds Max to search for user macro-scripts in addition to the user macro-script folder defined through the Configure User and System Paths dialog. By default, user macro scripts are stored in C:\Users\<username>\AppData\Local\Autodesk\3dsMax\<year> - 64bit\<language>\usermacros. In Maxscript and Python the $userMacros symbolic pathname represents this location.

The paths specified through this environment variable are searched after the user defined macro-scripts location. Multiple simultaneous 3ds Max sessions can execute with different values of this environment variable. If any of the paths defined through this environment variable are incorrect, an error is logged to the system log (Max.log).

User Icons Folders

An environment variable named ADSK_3DSMAX_ICONS_ADDON_DIR allows for defining a list of semicolon delimited paths which are used by 3ds Max to search for user defined icons in addition to the user icons folder defined through the Configure User and System Paths dialog. By default, user icons are stored in C:\Users\<username>\AppData\Local\Autodesk\3dsMax\<year> - 64bit\<language>\usericons. In Maxscript and Python represents the $userIcons symbolic pathname represents this location.

The paths specified through this environment variable are searched after the user defined icons location. Multiple simultaneous 3ds Max sessions can execute with different values of the environment variable. If any of the paths defined through this environment variable is incorrect, an error is logged to the system log (Max.log).

User Plugins Folders

An environment variable named ADSK_3DSMAX_PLUGINS_ADDON_DIR allows for defining a list of semicolon delimited paths which are used by 3ds Max to search for 3rd party plugins in addition to the folders defined through the Configure User and System Paths dialog. The following configuration files stores user plugin paths: C:\Users\<username>\AppData\Local\Autodesk\3dsMax\<year> - 64bit\<language>\Plugin.UserSettings.ini. In Maxscript and Python the pluginPath struct provides script access to the user defined plugin paths.

The paths specified through this environment variable are searched after the user defined plugin search locations. Multiple simultaneous 3ds Max sessions can execute with different values of the environment variable. If any of the paths defined through this environment variable is incorrect, an error is logged to the system log (Max.log).

User Plugins Package Folders

An environment variable named ADSK_APPLICATION_PLUGINS allows for defining a list of semicolon delimited paths which are used by 3ds Max to search for plugins packages in addition to the built in locations %ALLUSERSPROFILE%\Autodesk\ApplicationPlugins\ and %APPDATA%\Autodesk\ApplicationPlugins. In Maxscript and Python the $publicExchangeStoreInstallPath and $privateExchangeStoreInstallPath symbolic pathnames represent these locations.

The paths specified through this environment variable are searched after the built in plugin package search locations. Multiple simultaneous 3ds Max sessions can run with different values of this environment variable. If any of the paths defined through this environment variable are incorrect, an error is logged to the system log (Max.log).

For more details on the ADSK_APPLICATION_PLUGINS environment variable please see the "Packaging Plug-ins" topic in the C++ Developer Guide.

User Map Folders

An environment variable named ADSK_3DSMAX_ASSETS_MAPS_DIR allows for defining a list of semicolon delimited paths which are used by 3ds Max to search for maps in addition to the folders defined through the Configure Project Paths dialog's External Files tab. The list of map paths is stored in the project file (although it is also duplicated in 3dsmax.ini). The mapPaths struct exposed to Maxscript and Python gives scripters access to customizing these search paths.

The paths specified through this environment variable are searched after the user defined maps search locations. Multiple simultaneous 3ds Max sessions can run with different values of this environment variable. If any of the paths defined through this environment variable are incorrect, an error is logged to the system log (Max.log).

XRefs Folders

An environment variable named ADSK_3DSMAX_ASSETS_XREFS_DIR allows for defining a list of semicolon delimited paths which are used by 3ds Max to search for xrefs in addition to the folders defined through the Configure Project Paths dialog's XRefs tab. The list of xref paths is stored in the project file (although it is also duplicated in 3dsmax.ini). In Maxscript and Python the xrefPaths struct gives scripters access to customizing these search paths.

The paths specified through this environment variable are searched after the user defined XRef search locations. Multiple simultaneous 3ds Max sessions can execute with different values of the environment variable. If any of the paths defined through this environment variable is incorrect, an error is logged to the system log (Max.log).

3ds Max Projects (mxp files)

3ds Max project settings (paths) are defined in .mxp files that are similar in format to .ini files.

Note that when 3ds Max starts up, all paths that are defined by the project file are re-written to the 3dsmax.ini file. Therefore, if you wish to customize any of the project specific paths, you should do it through the project file and not 3dsmax.ini.

The project folder’s location can be configured using the ADSK_3DSMAX_PROJECT_DIR environment variable. To customize individual folders that are part of the project, you can use a startup script.

The following is a list of the paths (keys) that are defined and controlled through project files (.mxp):

Section	Key
Directories	Animations Archives AutoBackup BitmapProxies CFD Downloads Export Expressions Images Import Materials MaxStart Photometric Previews ProjectFolder RenderAssets RenderOutput RenderPresets Scenes Sounds VideoPost
XReferenceDirs	alldirs
BitmapDirs	alldirs

Customization through Environment Variable Tokens

This feature allows you to construct paths defined in various 3ds Max configuration files, including 3dsmax.ini, using user-defined environment variables, referred to as "environment variable tokens". The tokens are expanded to the value of the corresponding environment variable by 3ds Max at run-time, effectively allowing for easy programmatic construction of paths used in defining and configuring the 3ds Max environment consisting of user scripts and plugins, asset search paths, etc.

The tokens are expected in the following format:

%<token_name>%, where <token_name> is the name of a system or user environment variable.

Examples:

Non-tokenized user startup scripts path found in 3dsmax.ini:

Additional Startup Scripts=C:\Users\<username>\AppData\Local\Autodesk\3dsMax\<year>- 64bit\ENU\scripts\startup

Tokenized user startup scripts path:
```
 Startup Scripts=%NEW_3DSMAX_USER_SCRIPTS_ROOT%\startup, 
		
```
Where NEW_3DSMAX_USER_SCRIPTS_ROOT is the name of an environment variable whose value is the location where the user will expect 3ds Max user-defined scripts.

Details:

The expanded form of the tokenized paths is displayed in the user interface of 3dsMax, and is accessible through Maxscript and C++ APIs. The user is not prevented from editing/modifying the paths through the user interface, through Maxscript or the C++ API. Their changes to these paths will not overwrite the token-based setups in the configuration files. The changes will be effective only in the current 3ds Max session.

When an environment variable token expansion fails, the token is kept as is in the path, an error is logged to Max.log, but no errors are displayed to the user. Features of 3ds Max relying on those paths may each detect and react differently to the invalid path, some popping error dialogs, while others failing more silently.

Nesting tokens is not supported

Supported configuration files and paths

Below is the list of configuration files and the paths in them that support token expansion.

3dsmax.ini

Section	Keys
`Directories`	All keys supported
`CuiConfiguration`	Current Hotkey Dir
`PreRenderScriptDirs`	All keys starting with "Dir"
`PostRenderScriptDirs`	All keys starting with "Dir"
`RenderPrestetsMruFiles`	All keys starting with "RenderPresetsMruFile". Note that they can be overwritten.
`Performance`	ArchiveProg

ParticleFlowToolsBox3.ini

All paths in the Presets section support environment variable tokens.

MaxDotNet.config

All paths in the Plugin Directories section support environment variable tokens.

Plugin.ini and Plugin.UserSettings.ini

All paths in the Directories and Include sections support environment variable tokens.

Auto-tokenization of the 3ds Max installation paths in configuration files

Several paths found in configuration files such as 3dsmax.ini point to the 3ds Max installation folder. When the installation folder name needs to change due to pipeline or other requirements, updating the paths in the configuration files represents additional work and complexity. To solve the problem, 3ds Max now supports automatic tokenization of paths pointing to the 3ds Max installation folder, in the following configuration files:

%LOCALAPPDATA%\Autodesk\3dsmax\<year>- 64bit\<lang>\3dsmax.ini
%LOCALAPPDATA%\Autodesk\3dsmax\<year>- 64bit\<lang>\plugcfg_ln\ParticleFlowToolsBox3.ini

%LOCALAPPDATA%\Autodesk\3dsmax\<year>- 64bit\<lang>\plugcfg\MaxDotNet.config
%HOMEPATH%\Documents\3ds Max<year>\3ds Max 2021.mxp
<MaxInstall>\<lang>\plugin.ini

The auto-tokenization of 3ds Max install paths is disabled by default. It can be enabled through a command line switch or environment variable, as follows:

 ADSK_3DSMAX_ENVVAR_TOKEN_SUPPORT=1|0 
3dsmax.exe -envvartoken

When auto-tokenization is enabled, the root of the 3ds Max installation folder is replaced in the above configuration files with the %ADSK_3DSMAX_ROOT% environment variable token. The ADSK_3DSMAX_ROOT environment variable is defined by the 3ds Max process itself. The user doesn't need to define it.

For example, if 3ds Max is installed or deployed to C:\GameABC\ver1.2\3dsmax\2022\, the "Startup Scripts" key in 3dsmax.ini is set to %ADSK_3DSMAX_ROOT%\scripts\startup, where %ADSK_3DSMAX_ROOT% is an environment variable defined by 3ds Max at run-time and set to C:\GameABC\ver1.2\3dsmax\2022.

Notes:

The auto-tokenization of paths will not have an effect on already existent paths in the configuration files. In other words, the auto-tokenization works best when the configuration files are created by 3ds Max from scratch.

The Bitmap paths saved in 3dsmax.ini are not tokenized (and they don't need to be). These paths are a copy of the ones in the project file and are there for legacy reasons. 3ds Max will automatically update these paths in the 3dsmax.ini file if the installation folder changes.