Packaging Plug-ins

Plug-ins can be packaged using the Autodesk Application Plug-in Package format, which makes it easy to distribute them on the Autodesk App Store, and simplifies plug-in development and installation in 3ds Max.

A plug-in package, or bundle, consists of a folder structure containing all files related to the plug-in, and an XML file that defines the various components of the plug-in. Deploying plug-ins in this format, makes it easier to target multiple operating systems and product releases since the parameters of your plug-in are defined in the XML file of the package. Plug-ins using the package format can be installed without having to know the location where 3ds Max is installed, and their installers can simply copy the plug-in package into one of ApplicationPlugins folders described below in 'Install Locations'. 3ds Max scans the ApplicationPlugins folders and loads all applicable plug-ins.

Setting up a plug-in package is straight-forward. To do so you:

  1. Create an xml file named PackageContents.xml that describes your plug-in's components. See the detailed description below and the Autodesk Application Plug-in Package Format Specification topic.
  2. Create the physical layout of your plug-in consisting in all the files and folders that it needs. Besides the main binary, or script that represents your plug-in, it may have additional binary dependencies, macro scripts, icons, help file, etc. Place the PackageContents.xml file in the root folder of your plug-in package. To test it, you can set the ADSK_APPLICATION_PLUGINS environment variable to the root folder of your plug-in package. This environment variable is recognized by 3ds Max starting with version 2019.
  3. Optionally, you can create a zip archive of your plug-in package (including the PackgeContents.xml file) to upload to the Autodesk App Store. The App Store also provides a method of uploading all the files and creating a zip.

Install Locations

3ds Max supports these locations for plug-in installation using the Autodesk Application Plug-in Package format:

%ALLUSERSPROFILE%\Autodesk\ApplicationPlugins\[plugin_name]
Example:
C:\ProgramData\Autodesk\ApplicationPlugins\MyPlugin

This is the preferred install location when a plug-in is installed by the Autodesk store installer. Plug-ins installed to this location are available to all users on the machine.
%APPDATA%\Autodesk\ApplicationPlugins\[plugin_name]
Example:
C:\Users\<username>\AppData\Roaming\Autodesk\ApplicationPlugins\MyPlugin
This is the fallback install location when a user does not have administrator privileges, and it allows only that user to access the plug-in through 3ds Max.
Custom folder
3ds Max looks at the ADSK_APPLICATION_PLUGINS environment variable for a list of paths from which it will load plugin packages. These paths can point to either: 1) a directory containing a single plugin package XML file, allowing you to load only a specific plugin, or 2) a "parent" directory that contains one or more sub-directories that contain a plugin package XML file, allowing you to bulk load multiple plugins from a single path. The ADSK_APPLICATION_PLUGINS environment variable can contain a mix of these path types.
Note: Parent paths for multiple plugin packages was first available with 3ds Max 2019, single paths for specific plugin packages was first available in 3ds Max 2022.2 Update.

Example 1: Loading multiple plugin packages by specifying path to their parent folder In this example, various plugins for a certain version of 3ds Max, perhaps from different vendors, are located in sub-directories of:

D:\Plugins\3dsMax2022\:
D:\Plugins\3dsMax2022\Plugin1
D:\Plugins\3dsMax2022\Plugin2
...
D:\Plugins\3dsMax2022\PluginN

To instruct 3ds Max 2022 to load all plugins under \Plugins\3dsMax2022, you would set: ADSK_APPLICATION_PLUGINS=D:\Plugins\3dsMax2022

Example 2: Loading different plugin packages, or different versions of the same plugin, based on the needs of the projects being worked on. In this example, various plugins, sometimes different versions of the same plugin are stored on a server. The ADSK_APPLICATION_PLUGINS environment variable is configured differently based on the project the user works on:

\\Plugins\3dsMax2022\Plugin1.0
\\Plugins\3dsMax2022\Plugin2.1
\\Plugins\3dsMax2022\Plugin2.4
...
\\Plugins\3dsMax2022\PluginN.1.1

For Project 1, Plugin2.1 is needed, while for Project 2 Plugin2.4 is needed, therefore the environment variables specific for the 2 projects are set to point precisely to the folders representing the required plugins.

Setup for Project 1: ADSK_APPLICATION_PLUGINS=\\Plugins\3dsMax\Plugin2.1;\\Plugins\3dsMax\Plugin1.0 Setup for Project 2: ADSK_APPLICATION_PLUGINS=\\Plugins\3dsMax\Plugin2.4;\\Plugins\3dsMax\Plugin1.0

Note: The standard enforces the location of the package file, not the location of the 3ds Max plug-in files. The package file format uses paths to the files. These can be anything you want.

A basic package XML file

The following is an example of a simple Autodesk Application Plug-in package file for a utility plugin named MyPlugin.dlu that is compatible with 3ds Max 2020:

    <?xml version="1.0" encoding="utf-8"?>
    <ApplicationPackage 
        SchemaVersion="1.0" 
        AutodeskProduct="3ds Max" 
        ProductType="Application" 
        Name="My 3ds Max Plugin"
        AppVersion="1.0.0"
        UpgradeCode="{bef4b961-c3dc-4197-b663-ed8dde1197ee}"
        ProductCode="{07849d02-b914-4593-bf03-49bdd74526d0}">
        <CompanyDetails />
        <Components Description="plugin parts">
            <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2020" SeriesMax="2020" />
            <ComponentEntry ModuleName="./Contents/MyPlugin.dlu" />
        </Components>
    </ApplicationPackage>

At the top level, the package format requires a node called <ApplicationPackage>. The "AutodeskProduct" attribute defines which product the package is meant for, in this case 3ds Max. The "ProductType", in the context of 3ds Max plug-ins, is always "Application". The "AppVersion" is a version string in the format "MMM.mmm.bbb" (major.minor.build). Using the version string, two packages with different versions can co-exist. The package with the higher version will be loaded. The "UpgradeCode" is the unique identifier for the plug-in package. Only one package with a particular product code will be loaded. The "ProductCode" is a unique identifier that needs to be changed every time the AppVersion changes.

The <CompanyDetails> node can contain publisher details. It is mandatory, but the content is optional.

The <Components> node lists a group of files that need to be managed by the application. These are associated with a "Description", which defines what to do with these files. See the Autodesk Application Plug-in Package Format Specification topic for a list of valid description strings. The "plugin parts" value tells the application to load these as plug-in DLLs.

The <RuntimeRequirement> needs to be defined for each <Components> node. Defining runtime requirements per components can be valuable when creating a plug-in that targets multiple releases of 3ds Max. In this case, a <Components> node per 3ds Max release would define the appropriate component (plug-in dll) and run-time requirement (version of 3ds Max the plug-in dll was built for). Generally, plug-in DLLs will need to be matched with a version of 3ds Max they have been built for, while scripts and other files could be shared for all supported 3ds Max releases.

The folder structure for the above plug-in package could look like: C:\Plugins\bin\MyPlugin\PackageContents.xml C:\Plugins\bin\MyPlugin\Contents\MyPlugin.dlu C:\Plugins\bin\MyPlugin\Contents\en-US\MyPlugin.dlu.mui

For a more complete example of a plug-in package see the Example Plug-in Package topic.

Debugging Plugin Packages

When an error occurs while loading plugin packages, 3ds Max will display an error message. In case you need to turn off this behavior, you will need to create an entry in 3dsmax.ini:

[PluginPackageManager]
ShowMessageDialogOnError=0
Parent page: Packaging Plug-Ins