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"?>
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.
| 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. |
The plug-in will not load if this element is not defined.
All attributes are optional.
| 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 |
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.
| 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". This property does not support point releases, such as "2020.1". |
| 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". This property does not support point releases, such as "2020.1". |
Recommend 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".
3ds Max will detect if the series specified is binary compatible with the running version, and load the plug-in if it is. For example, if the SeriesMin and SeriesMax is 2015, 3ds Max 2016 is binary compatible, and will load the plug-in.
<Components Description="xxx"> ... </Components>
This node describes a component, its runtime requirements, and a list of component entries. The "Description" attribute defines how to load the component entries. Possible valid values are listed below.
| 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 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. | |
| Tag | Description |
|---|---|
| plugins parts | Loads the file defined by ModuleName attribute of ComponentEntry element as a 3ds Max plug-in DLL |
| assemblies parts | Loads the file defined by ModuleName attribute of ComponentEntry element as a managed assembly DLL |
| ui schemes parts | The file defined by ModuleName attribute of ComponentEntry element defines a UI scheme file that can be used by the defaults switcher |
| default setting paths parts | The Loads the file defined by ModuleName attribute of ComponentEntry element defines a folder where defaults are stored |
| pre-start-up scripts parts | Loads the file defined by ModuleName attribute of 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 ModuleName attribute of ComponentEntry element as macro scripts |
| post-start-up scripts parts | Loads the file defined by ModuleName attribute of ComponentEntry element as a startup script. The UI system is fully in place. |
| light icon paths parts | Loads the path defined by ModuleName attribute of ComponentEntry element will be added as a path to the CUI frame manager to load light icons from |
| dark icon paths parts | Loads the path defined by ModuleName attribute of ComponentEntry element will be added as a path to the CUI frame manager to load dark icons from |
See Example Plug-in Package for an example of how to use <ComponentEntry>.