Autodesk Application Plug-in Package Format Specification

This topic describes the elements that can make up a package XML (PackageContents.xml) file for a 3ds Max plug-in.

• Autodesk Application Plug-in Package Format Specification
  • XML version (required)
  • <ApplicationPackage> (required)
    • <ApplicationPackage> Attributes
  • <CompanyDetails> (required)
    • <CompanyDetails> Attributes
  • <RuntimeRequirements>
    • <RuntimeRequirements> Attributes
  • <Components>
    • <Components> Sub Nodes
    • <Components> Description attribute values
  • <EnvironmentVariables> (optional)
  • <EnvironmentVariable> (optional)
    • <EnvironmentVariable> Attributes
  • <DependentBundles> (optional)
  • <LoadAfterBundles> (optional)
  • DependentBundles specification in ComponentEntry node

XML version (required)

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

<CompanyDetails> (required)

The plug-in will not load if this element is not defined. All attributes are optional.

<CompanyDetails> Attributes

<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

The SeriesMin and SeriesMax attributes support version specification in the form of YYYYY.u.h.bbbb (e.g. "2021.2.1.4567"), where:

• YYYY is the product release year (e.g. "2022")
• u is the update number (e.g. "2" for 2022 Update 2)
• h is the hotfix number (e.g. "1" for 2022 Update 2, Hotfix 1)
• bbbb is the build number (e.g. "4567")

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

<Components> Description attribute values

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

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

For example:

Defining a new environment variable:

<EnvironmentVariable Name="GPU_PLATFORMS" Value="titan;gtx 980" Type="string"></EnvironmentVariable>

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"></EnvironmentVariable>

The environment variable is now GPU_PLATFORMS=titan;gtx 980;amd

Removing a substring:

<EnvironmentVariable Name="GPU_PLATFORMS" Value="-;gtx 980" Type="string"></EnvironmentVariable>

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.

For example:

Adding a path to PYTHONPATH:

<EnvironmentVariable Name="PYTHONPATH" Value="\+;.\Contents" Type="PATH"/></EnvironmentVariable>

<DependentBundles> (optional)

Available in 3ds Max 2025.

To be able to specify for a package what other packages are required in order for the package to be loaded. For example, CRaySuperCam package may require that the CRay package be present. Along with the required package, specific versions of that package may be required.

To be able to specify for a package what other packages (if present) should be loaded before the package. For example, CRaySuperCam package may require that the VRay package be loaded first.

To meet these intents, package files can now specify DependentBundles and LoadAfterBundles. 

Within a DependentBundles element, zero or more DependentBundle elements can be specified. The attributes of a DependentBundle element are UpgradeCode, VersionMin and VersionMax. The VersionMin and VersionMax attributes are optional.  

If UpgradeCode is specified, other package(s) must be present. If not present, this package is not loaded.

The VersionMin and VersionMax values, if specified, are compared to the AppVersion specification for the package associated with UpgradeCode. The format of the VersionMin and VersionMax values is the same as for AppVersion.

An example specification is:

    <DependentBundles>
        <DependentBundle UpgradeCode="{10A09F68-8A8B-432C-97EF-63430FD84997}" VersionMin="1" VersionMax="1" />
    </DependentBundles>
    

<LoadAfterBundles> (optional)

Available in 3ds Max 2025.

Within a LoadAfterBundles element, zero or more LoadAfterBundle elements can be specified. The only attribute of a LoadAfterBundle element is UpgradeCode.  

An example specification is:

    <LoadAfterBundles>
        <LoadAfterBundle UpgradeCode="{2024147C-9C98-4C54-B59A-E1A583DDB62B}" />
    </LoadAfterBundles>

It is possible that the LoadAfterBundles specifications for a set of bundles results in a circular dependency. As the LoadAfterBundle elements are processed they are checked to ensure that a circular dependency does not occur. If one does occur, an error message is logged to the Plug-in Package Manager Error Messages dialog and the LoadAfterBundle is ignored.

The UpgradeCode value for DependentBundle and LoadAfterBundle elements is validated to ensure it is valid (in the form "{2024147C-9C98-4C54-B59A-E1A583DDB62B}" or "2024147C-9C98-4C54-B59A-E1A583DDB62B"), and if not an error message is logged to the Plug-in Package Manager Error Messages dialog and the element is ignored.

When LoadAfterBundle elements are present after loading all package specifications and the pruning of any packages excluded via DependentBundle specifications, the lists of components will be sorted to reflect the LoadAfterBundle specifications. The order of component entries are maintained for a package, and component entries for packages not affected by the LoadAfterBundle specifications are placed above those affected by the specifications.

For example, with a Components specification of:

    <Components Description="post-start-up scripts parts">
        <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="0" SeriesMax="9999" />
        <ComponentEntry ModuleName="./Contents/Scripts/Script1.ms" />
        <ComponentEntry ModuleName="./Contents/Scripts/Script2.ms" />
    </Components>

Script1.ms will always be run before Script2.ms, regardless of LoadAfterBundle specifications.

If you have three packages A, B, and C where the LoadAfterBundle specifications specify that package A load after package C, the component entries for the various component lists would be sorted such that the component entries associated with B would be first (since not affected by LoadAfterBundle specifications), then C, then A.

Note that in order for DependentBundles and LoadAfterBundles to work correctly, the UpgradeCode for all packages must be proper guid string values.

Example error messages:

Bad UpgradeCode value "{x10a09f68-8a8b-432c-97ef-63430fd84997}" in DependentBundle for package "package_1_5" in folder "G:\2025\3dswin\bin\x64\Hybrid\ApplicationPlugins\package_1_5\", ignored.
Bad UpgradeCode value "{x2024147c-9c98-4c54-b59a-e1a583ddb62b}" in LoadAfterBundle for package "package_1_5" in folder "G:\2025\3dswin\bin\x64\Hybrid\ApplicationPlugins\package_1_5\", ignored.
Circular dependendency detected while handling LoadAfterBundle "{407924df-767d-48ad-bcaf-9cac9ffb8349}" for package "package_4_4" in folder "g:\2025\3dswin\bin\x64\hybrid\applicationplugins\package_4_4\", ignored. 

DependentBundles specification in ComponentEntry node

Available in 3ds Max 2025.

DependentBundles specification in ComponentEntry node is supported so that the ComponentEntry is not loaded if the specified DependentBundle(s) are not present.

For example:

  <Components Description="post-start-up scripts parts">
      <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="0" SeriesMax="9999" />
      <ComponentEntry ModuleName="./Contents/Scripts/testScript.ms">
          <DependentBundles>
              <DependentBundle UpgradeCode="{10A09F68-8A8B-432C-97EF-63430FD84997}" VersionMin="1" VersionMax="1" />
          </DependentBundles>
      </ComponentEntry>
  </Components>

testScript.ms would not be loaded unless package with upgrade code of {10A09F68-8A8B-432C-97EF-63430FD84997} is present and has app version of 1.