This topic describes the elements that can make up a package XML (PackageContents.xml) file for a 3ds Max plug-in.
Example: <?xml version="1.0" encoding="utf-8"?>
<ApplicationPackage> (required)Each PackageContents.xml file must contain an ApplicationPackage element. The ApplicationPackage element's attributes contain general information about the plug-in. It also encapsulates other XML elements (nodes) that help to define the contents of the plug-in.
The <ApplicatonPackage> must have a <CompanyDetails> node.
It can optionally contain a <RuntimeRequirements> node.
It also contains an array of 0 or more <Components> nodes.
Starting with 3ds Max 2023 it can optionally contain one or more <EnvironmentVariables> node.
<ApplicationPackage> Attributes| Name | Description |
|---|---|
| AutodeskProduct (required) | Must be set to "3ds Max" |
| ProductType (required) | Must be set to "Application" |
| Name (optional) | Plug-in name |
| Description (optional) | Plug-in description |
| AppVersion (required) | Version string in the form of "MMM.mmm.bbb" (major.minor.build) |
| UpgradeCode (required) | Unique identifier (GUID) for the plug-in that should be used for all its versions. If 3ds Max finds two packages with the same UpgradeCode, it will load the one with the higher AppVersion. Note: You must increment AppVersion in order to allow for proper upgrading of a plug-in. When you upload your plugin package to the Autodesk App Store in order to publish it, this code is used for generating an installer that will upgrade existent installations of previous versions of your plugin, without the need to uninstall the old version first. |
| ProductCode (optional/required) | This property is not required by 3ds Max. However, if the plug-in package is distributed through the Autodesk App Store, it is required, and the following description applies: This is the unique identifier (GUID) for a specific version of the plug-in. The ProductCode is used for first run notifications and as the installer ID for Add/Remove Programs in Windows when installed from the Autodesk App Store website. A new ProductCode should be used whenever the AppVersion is changed. This is so upgrade installs of the plugin package work properly. On Windows, you can use the MSI installer ProductCode or generate a GUID using an application such as GuidGen.exe. There are also websites that allow you to generate a GUID. |
<CompanyDetails> (required)The plug-in will not load if this element is not defined. All attributes are optional.
<CompanyDetails> Attributes| Name | Description |
|---|---|
| Url | URL to reference back to the company |
| E-mail, read as a string, no format required | |
| Phone | Phone, read as a string, no format required |
| Name | Company name |
<RuntimeRequirements>This element enables the plug-in's host application to quickly process an application plug-in package. It identifies which operating systems, Autodesk products and releases the package is compatible with.
Optional in the <ApplicationPackage> node.
Required in the <Components> nodes.
<RuntimeRequirements> Attributes| Name | Description |
|---|---|
| OS | Must be set to "Win64" |
| Platform | Must be set to "3ds Max" |
| SeriesMin | The minimum 3ds Max release the plug-in is compatible with. Currently this should be the 3ds Max product release number the application is compatible with. For example, it might be "2020". Year, build, update, and hotfix versions are also supported - see below. If not specified, a value of 0 is used. |
| SeriesMax | The maximum 3ds Max release the plug-in is compatible with. Currently this should be the 3ds Max product release number the application is compatible with. For example, it might be "2020". Year, build, update, and hotfix versions are also supported - see below. |
The SeriesMin and SeriesMax attributes support version specification in the form of YYYYY.u.h.bbbb (e.g. "2021.2.1.4567"), where:
Recommended practice:
When creating a DLL that is compiled with the 3ds Max SDK, SeriesMin and SeriesMax should specify the "release year" range the plug-in is compatible with.
The plug-in DLL should be binary compatible with all the application releases that fall between the values specified in SeriesMin and SeriesMax.
Note that 3ds Max does not test for binary compatibility. Even if the current version of 3ds Max is binary compatible with an older SeriesMax version, the plugin is not loaded. For example, if the SeriesMin and SeriesMax is 2015, 3ds Max 2016 is binary compatible, but will not load the plug-in.
The SeriesMax attribute is mandatory.
<Components><Components Description="xxx">
...
</Components>This node describes a component, its runtime requirements, and a list of component entries. The "Description" attribute is required and defines how to load the component entries. Possible valid values are listed below.
<Components> Sub Nodes| Name | Description |
|---|---|
<RuntimeRequirements> (required) |
See above table for runtime requirements which can be specified for more specific modules here. For example, SeriesMin and SeriesMax may be different for a specific component. |
<ComponentEntry ModuleName="XXX" /> |
List of ComponentEntry nodes. At least one needs to be present. Each defines a file to be loaded through its "ModuleName" attribute, which can be an absolute or relative file path to the package XML file. You can specify a wildcard in the file name, such as "*.ms" to specify all MAXScript files. Wildcards are supported in file names only, not in file paths. If a file is specified twice, 3ds Max will display an error message. |
<Components> Description attribute values| Tag | Description |
|---|---|
| plugins parts | Loads the file defined by the ModuleName attribute of the ComponentEntry element as a 3ds Max plug-in DLL. |
| assemblies parts | Loads the file defined by the ModuleName attribute of the ComponentEntry element as a managed assembly DLL. |
| ui schemes parts | The file defined by the ModuleName attribute of the ComponentEntry element defines a UI scheme file that can be used by the defaults switcher. |
| default setting paths parts | The path in the ModuleName attribute of the ComponentEntry element defines a folder where defaults are stored. |
| pre-start-up scripts parts | Loads the file defined by the ModuleName attribute of the ComponentEntry element as a plug-in script. This is done after plug-in DLLs are loaded. The UI system is not yet in place so scripts have "limited" functionality. Only MAXScript scripts are supported here. |
| macroscripts parts | Loads the file defined by the ModuleName attribute of the ComponentEntry element as a macroscript. |
| post-start-up scripts parts | Loads the file defined by the ModuleName attribute of the ComponentEntry element as a startup script. The UI system is fully in place. MAXScript and Python scripts are supported here. |
| light icon paths parts | The path defined by the ModuleName attribute of the ComponentEntry element will be added as a path to the CUI frame manager to load light icons from. |
| dark icon paths parts | The path defined by the ModuleName attribute of the ComponentEntry element will be added as a path to the CUI frame manager to load dark icons from. |
| scene converter folders parts | The path defined by the ModuleName attribute of the ComponentEntry element is used by the Scene Converter to load preset and conversion scripts. Presets are loaded from a sub-directory named ConversionPresets, and have pattern [name]_preset.ms. Conversion scripts are loaded from a sub-directory named ConversionScripts. |
| osl folders parts | The path defined by the ModuleName attribute of the ComponentEntry element is parsed for OSL shaders and loaded. The last (main) directory in this path must be named OSL. Sub-directories are added as categories in the list of OSL shaders. |
| amg folders parts | The path defined by the ModuleName attribute of the ComponentEntry element is parsed for AMG shaders and loaded. Any sub-directory that exists in the system AMG directory can also exist under this folder, and will be used in the same way. AMG files in the system AMG directory are loaded first. |
| hotkey parts | The .hsx file defined by the ModuleName attribute of the ComponentEntry element is parsed for hotkey definitions. |
See Example Plug-in Package for an example of how to use <ComponentEntry>.
<EnvironmentVariables> (optional)This element provides a way for plug-ins to define environment variables for the 3ds Max process. This element contains a <RuntimeRequirements> element (required) and one or more optional <EnvironmentVariable> elements that define environment variables available to the running 3ds Max process. Environment variables can be defined, modified, or removed.
<EnvironmentVariable> (optional)Each <EnvironmentVariable> element defines an environment variable that is created when the package is loaded, and is available to that instance of 3ds Max. All environment variables are processed before 3ds Max loads any components. An environment variable can only be defined once, but can be appended or prepended multiple times. Two plug-ins cannot define the same environment variable, but they can append to an already defined environment variable.
<EnvironmentVariable> Attributes| Tag | Description |
|---|---|
| Name (required) | The name of the environment variable. Note: environment variable names are case sensitive. |
| Value (required) | The value of the environment variable, specified as a string. |
| Type (required) | The type of the environment variable, either "string" or "path". |
You can use OS defined variables in the value, which get expanded when the environment variable is created. For example, %LOCALAPPDATA%/Renderer/Cache is expended to C:/Users/<username>/AppData/Local/Renderer/Cache. If the expansion fails (the variable is not defined, for example), no environment variable is created and an error is written to max.log.
The value can optionally start with one of these operators:
< - prepends the value to the existing definition+ - appends the value to the existing definition, or if the type is a path, adds the path if it is not already in the list- - removes the value from the existing definition, or if the type is a path, removes the path from the list Operators can be escaped by using the backslash character, eg: \+.
For example:
Defining a new environment variable:
<EnvironmentVariable Name="GPU_PLATFORMS" Value="titan;gtx 980" Type="string">Results in the environment variable: GPU_PLATFORMS=titan;gtx 980
Appending a value (note that the separator is part of the appended string):
<EnvironmentVariable Name="GPU_PLATFORMS" Value="+;amd" Type="string">The environment variable is now GPU_PLATFORMS=titan;gtx 980;amd
Removing a substring:
<EnvironmentVariable Name="GPU_PLATFORMS" Value="-;gtx 980" Type="string">Results in: GPU_PLATFORMS=titan;amd
If the environment variable is a "path" type: 3ds Max normalizes and resolves relative paths before creating the environment variable. Paths that are not fully qualified are resolved relative to the PackageContents.xml that defines them. Plugins do not need to resolve relative paths themselves. If the path is invalid, the environment variable is not defined and the error is logged to max.log. 3ds Max continues to execute and load plugins.