This topic describes the elements that can make up a package XML (PackageContents.xml) file for a 3ds Max plug-in.
Note: The way 3ds Max handles plug-in packages differs slightly from the way other Autodesk products such as AutoCAD do. Specifically, 3ds Max does not require the ProductCode element, but does require the UpgradeCode element. See details in the table below.
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.
<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. |
| 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. |
| 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. |
See Example Plug-in Package for an example of how to use <ComponentEntry>.