Example Plug-in Package

This example will walk through creating and packaging a simple MAXScript-based plug-in that has assorted assets configured as components in the PackageContents.xml file, using the Autodesk Application Plug-in Package format.

Let's start with a sample script, save it as menu_demo.ms . This macroscript creates a new menu under the main 3ds Max Help menu:

-- Create a custom menu item with an icon
macroScript demo_icon_menu category: "mxs docs" tooltip:"My Test Menu Item"
IconName:"test1.ico"
(
    On Execute Do    
    (
        print "My Test Menu Item executed"
    )
)

-- Menu callback function that contains our custom menu code
function menuCallback =
(
    -- Retrieve the menu manager, that's currently loading the menu structure, from the callback parameters
    local menuMgr = callbacks.notificationParam()

    -- Append our new test menu to the 3dsMax main menubar
    local mainMenuBar = menuMgr.mainMenuBar
    local myTestMenu = mainMenuBar.CreateSubMenu "F8FFB827-741C-4A81-8C89-BBF856DCF56D" "Demo Menu MXS"

    -- Add our test macro script action item to our menu
    local macroScriptTableId = 647394
    -- Our action identifier for the test action is the with '`' concatinated string of our macro script name and category
    local macroScriptTestActionId = "demo_icon_menu`mxs docs" 
    myTestMenu.CreateAction "ADB41E81-D249-4539-8F5B-2406E02D8352" macroScriptTableId macroScriptTestActionId
)
-- Register our menu creation callback so that it can be executed whenever the menu structure is evaluated.
callbacks.removeScripts id:#menuDemo
callbacks.addScript #cuiRegisterMenus menuCallback id:#menuDemo

We can create a the PackageContents.xml file for the above script that looks like this:

    <?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"
        ProductCode="{caedfa12-cf58-4188-a22b-e4cf2e52baa2}" 
        UpgradeCode="{68b04f36-d00b-436e-9386-7337afcffa4a}">
        <CompanyDetails />
    <Components Description="pre-start-up scripts parts">
        <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2025" SeriesMax="2025" />
        <ComponentEntry AppName="DemoMenu" Version="1.0.0" ModuleName="./pre_startup_scripts/menu_demo.ms" />
    </Components>
    </ApplicationPackage>

Here we specify a single component, a "pre-start-up script". Note that there are two types of start-up script parts. In this case, we run pre start up, because we need need to register our new menu during the ui setup phase of 3ds Max startup.

Create the following folder and file structure for testing:

• C:\Test\NewMenuDemo\PackageContents.xml
• C:\Test\NewMenuDemo\pre_startup_scripts\menu_demo.ms

Set the ADSK_APPLICATION_PLUGINS environment variable to C:\Test\

Launch 3ds Max to confirm that the script loads properly.

Adding Icons

To add the icon used by the plug-in, we need to set additional paths for 3ds Max to search for icons in. A plug-in should set both light and dark theme paths, even if the icons are the same for both themes. Our script is looking for a multi-resolution icon named "test1", so we will create an icon directory inside the package directory for each theme, and put the icons in them.

• C:\Test\NewMenuDemo\icons\dark\test1.ico
• C:\Test\NewMenuDemo\icons\light\test1.ico

We then add these components to the PackageContents.xml:

    <Components Description="light icon paths parts">
        <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2025" SeriesMax="2025" />
        <ComponentEntry AppName="lighticons" Version="1.0.0" ModuleName="./icons/Light" />
    </Components>
    <Components Description="dark icon paths parts">
        <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2025" SeriesMax="2025" />
        <ComponentEntry AppName="darkicons" Version="1.0.0" ModuleName="./icons/Dark" />
    </Components>

Adding more components involves adding the item to the package directory, and then adding a component entry to the PackageContents.xml file. For example, we can add another MAXScript called by our menu, called mxs_function.ms:

fn helloWorld msg = (
    format "Hello world %\n" msg
) 

This is also added to the pre-start-up scripts:

    <Components Description="pre-start-up scripts parts">
        <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2025" SeriesMax="2025" />
        <ComponentEntry AppName="DemoMenu" Version="1.0.0" ModuleName="./pre_startup_scripts/mxs_function.ms" />
    </Components>

Once you have tested that the package loads from the test folder, you can create a zip archive for upload to the Autodesk App Store, or add it to an installer for distribution to 3ds Max users, and install to one of the locations described in the Packaging Plug-ins topic.

OSL and AMG Shaders Example

This example shows how to package OSL shaders:

    <?xml version="1.0" encoding="utf-8"?> 
    <ApplicationPackage SchemaVersion="1.0" AutodeskProduct="3ds Max" Name="OSL and AMG Shaders" Description="OSL and AMG Plugin Package Example" AppVersion="1.0.0"    ProductType="Application" AppNameSpace="appstore.exchange.autodesk.com" Author="Autodesk" ProductCode="{89013b63-a8b6-4e83-81c0-9cc1ecbb308e}" UpgradeCode="{4f6e7e7c-ad40-4093-8063-4be9f1b78eb4}"> 
    <CompanyDetails Name="Autodesk Productions" Url="http://www.autodesk.com" /> 
    <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2021" SeriesMax="2021" /> 
    <Components Description="osl folders parts"> 
        <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2021" SeriesMax="2021" /> 
        <ComponentEntry ModuleName="./Contents/OSL/" /> 
    </Components> 
    <Components Description="amg folders parts"> 
        <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2021" SeriesMax="2021" /> 
        <ComponentEntry ModuleName="./Contents/AMG/" /> 
    </Components> 
    <Components Description="hotkey parts"> 
        <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2023" SeriesMax="2023" /> 
        <ComponentEntry ModuleName="./Contents/Hotkeys/SnapPivotHotkeys.hsx" /> 
    </Components> 
    </ApplicationPackage>