SD10586 Take 3ds Max to the Next Level with Customization (and Gain Kudos!) Kevin Vandecar Autodesk Inc. Denis Grigor Autodesk, Inc. Learning Objectives General customization aspects of 3ds Max Learn about scripting APIs MAXScript and Python Discover.NET API pros and cons! Learn about C++ SDK capabilities and why you might have to resort to the "dark side" Description This class will be a quick introduction to 3ds Max software scripting, customization, plug-in development, and general hacking. We will introduce each customization aspect, including the new Max Creation Graphs software, MAXScript scripting language, Microsoft.NET API, Python programming language, and the "dark side" C++ SDK. We also will show how you can gain notoriety in the 3ds Max software customization space by publishing your application to the Autodesk Exchange Store, and we ll discuss the various community aspects around 3ds Max software customization. Today's environment involves ingenuity and social capabilities, so why not talk about or publish your awesome 3ds Max software ideas and make a name for yourself? Your AU Experts Kevin Vandecar has worked for Autodesk, Inc., for 20 years in various customization-related capacities, ranging from developer support and testing to software development and consulting. He has also worked for a large reseller/consulting firm, and he has a customer-centric sensibility. Kevin currently is a principal developer consulting engineer and also the manager for the Media & Entertainment Autodesk Developer Network Workgroup. His current specialty is 3ds Max software customization areas, but he also has experience in AutoCAD, AutoCAD Architecture, AutoCAD MEP and Revit. Denis Grigor has a special bond with 3ds Max, ever since they first met about 15 years ago, which ultimately drew him to recently join Autodesk, Inc., and have the chance to talk to it on daily basis, either through C++, Python or MAXScript, depending how intimate the talk supposed to be. As a Developer Technical Consultant, his primary task is helping plugin developers to overcome the difficulties they encounter in their endeavor of mastering the 3ds Max SDK.
This course will introduce some of the many ways that 3ds Max can be customized. It will range from simple UI customizations to be more productive, through MAXScript, Python,.NET API, and finally we will introduce the 3ds Max C++ SDK. Note about Sample Code The sample code that accompanies this course is meant mainly to illustrate the different ways that 3ds Max can be customized in an easy to understand format. Because of this, there is minimal error checking and exception handling. If reusing any of the sample code in your production code, please remember to add appropriate error handling. 3ds Max Customization and Plug-in Development As you can guess from the title, this presentation is meant to give you a high-level overview of the different ways 3ds Max can be customized. We will touch on each area of customization with the What, Why and How answered through interactive demonstration, and code. The areas covered include general product customizations, MAXScript, Python,.NET API, and the C++ 3ds Max SDK components. Each of the programming environments could take up many AU based courses, so keep in mind that this is meant to be a general introduction to the various ways of customization 3ds Max. Feel free to let us know later those topics you might like to see more in-depth information! The general customization concepts are documented in the user guide online here: Customizing 3d Max The 3ds Max scripting and SDK documentation can be found online here: http://www.autodesk.com/me-sdk-docs 2
General Product Customizations These types of customizations mainly fall into a category of user interface driven tools. From the very new and popular Max Creation Graph, to the mundane ways of customizing paths and setting of custom unit values, these are all mainly controlled through UI based tools. These tools are at the heart of your users to be able to create a custom experience they are most comfortable with. What is Customize User Interface? In 3ds Max you can easily customize the user interface. All of the commands that are available are exposed through a facility called action items via the action system. These action items are named and categorized, and so will appear in the customize user interface dialog. Action system can be programmed through the SDK environments as well. Why would you customize the User Interface? The answer to this is probably obvious! Efficiency and convenience of course! By taking some time to make your most common commands accessible in the ways you prefer, you will become more productive. It might also help if your colleagues or project team have a similar workflow to share the customization. 3ds Max allows you to also share the customization, so in this situation you can be helping an entire team of artists or designers to become more productive. If you are developing plug-ins, then you will also probably want to expose the commands in a similar way as the built-in plug-ins do by implementing the action items in the plug-in. This way the users of your plug-ins can perform the same customization operations as they would for any other part of 3ds Max. How would you customize the User Interface? The customize pull-down menu offers a few different customization options. First select the Customize User Interface item. This opens the customize user interface dialog. See figure 1 for an example of the keyboard customization tab, using the CAT category of commands, with the action item listed. 3
Figure 1 What would you customize in the User Interface? The Customize User Interface dialog allows you to set keyboard shortcuts, create and modify toolbars, modify the Quad menu, and create or modify the pull-down menus. There is also a tab here for changing the user interface colors. The Ribbon interface can also be customized by simply right-clicking in an empty portion of the ribbon panel, select Ribbon Configuration, and Customize Ribbon A different dialog for customizing the ribbon is presented as shown in Figure 2. 4
Figure 2 The standard Customize User Interface items can be saved and loaded via a UI file set. This also will allow you to share the customizations with other users. Plug-ins implemented using MAXScript,.NET API, or the C++ SDK can also programmatically provide the customization and exposure of new action items. Additional Resources for customizing the user interface in 3ds Max: 3ds Max help: Customizing 3d Max Autodesk Forums: 3ds Max Programming Autodesk Product Support is providing support for this feature. The ADN DevTech team can help with programming aspects of the UI customization. 5
What is Max Creation Graph (MCG) The new Max Creation Graph feature has been wildly popular. An introduction to customization environments would not be complete without this new topic. However, there are separate courses and a lot fanfare around this, so we will not dive deep into this. MCG is a visual node based programming environment where you can interactively create graphs that act as plugins types such as geometry and modifiers. Why would you use MCG? It s easy and powerful! It s visual and node based! But it is an interpreted environment and does not include any protection so not ideal for a commercial solution. How would create custom tools with MCG? Simply launching the visual graph editor allows you to start or edit existing graphs. See the samples in the MCG folder. Additional Resources for using MCG: 3ds Max help: Max Creation Graph Autodesk Forums: Max Creation Graph (MCG) Autodesk Product Support is providing support for this feature. 6
What is MAXScript? MAXScript is the 3ds Max scripting language and is proprietary to the application. It is very robust and can control many aspects of 3ds Max. It is easier to use than C++ and is an interpreted language allowing you to run it easily without the application. It is supported by a special console window that allows direct execution of MAXScript code. There is also a MAXScript specific editor that allows you to code MAXScript and execute directly from the editor. Why would you use MAXScript? There are many reasons to use MAXScript. Essentially anything that is repetitive, that you need to perform regularly is a good candidate for MAXScripting. You may also want to provide UI customization via MAXScript. This would be a different approach to the UI file discussed earlier. Algorithmic operations that you may want to apply to a scene s geometry are also a great reason to use it. Almost anything 3ds Max does, MAXScript can automate! This includes the following functionality: User interface Geometry Cameras Lights Helpers Particles Modifiers Animation Controllers Trackview Renderer Materials Batch process files Batch process objects Import/Export How would you use MAXScript? MAXScript is part of the 3ds Max application. There is a pull-down menu to get started with the different options. You can enable the Listener Window that allows direct MAXScript entry. You can also enable the MAXScript editor that allows for creating new MAXScript code. The editor window has syntax coloring and checking that makes it easy to write MAXScript. The Macro Recorder option will enable the echoing of user entered commands, so you can use that syntax as examples for how to write MAXScript operations yourself. See figure 3 for the window layout. 7
Figure 3 MAXScript is stored as *.ms files and are text based. There are also auto-loading and running capabilities. See the samples in the MAXScript folder. Additional Resources for learning MAXScript 3ds Max help: MAXScript Help Autodesk Forums: 3ds Max Programming Autodesk Product Support is providing support for this feature. ADN DevTech team is backup. MAXScript docs and samples included with 3ds Max remember this is a separate download with your products now. Currently the extras are available from the Autodesk Knowledge network here: 3ds Max 2016 Sample Files. The samples download contains many MAXScripts ready for use, or repurposing for your own specific needs. Additionally, because the 3ds Max MAXScript language has a long history, there are many resources on the web that can help. 8
What is Python? Python scripting language has been around since the late 1980 s. See Python history from Wikipedia Very early it became popular because of the philosophy that it should be code that can be easily read and understood. This resulted in fewer syntactical punctuations as other languages such as C++ or C# with its braces and semi-colons, etc. This, however creates one problem (in the eye of the author, anyway, ). This idea means certain syntax rules become hidden and not always obvious for the coder. For example a tab, and 4 spaces can have different behavior in Python if you are not careful. Because it is an open source implementation of a scripting language, it quickly became the natural choice for technology consumption as well. Autodesk Maya for example, has been using it for many years now, and is one of the primary customization languages. For 3ds Max, it is relatively new, and was brought into 3ds Max to support the workflows that were already in place for many customers using other products. CPython is indicated to be the reference implementation of Python. The CPython implementation is the distribution mainly used by Autodesk. It is a free and open-source version and has a community-based development model. The CPython project is managed by the non-profit Python Software Foundation. CPython is named this way due to its internal implementation being written in the C programming language. This is one reason it is such a popular implementation, because it can easily be integrated into other C and C++ based technologies like 3ds Max. See https://www.python.org/ for the full details about python as a language. Why would you use Python? The first obvious reason would be because you have other tools already implemented in Python and have an experience pool. It is also very useful for automating certain tasks and building tools. Without experience in Python, it may not be your first choice for customization in 3ds Max. But it does have many general benefits that has drawn people to it. There are many benefits for using Python. For example: Large pool of people and knowledge. Ie. 250,000 questions and answers on StackOverflow.com Easy to re-use scripts Able to extend. Ie. CPython API, SIP, SWIG, Boost, etc. Easy to learn Good for exploratory programming Many reusable libraries How would you use Python? 3ds Max includes the CPython 2.7.3 version as a DLL. Being a DLL means that it runs in-process with 3ds Max. This allows execution of Python scripts directly in the 3ds Max process. The integration entry point is made via the MAXScript interface. The primary way to execute Python is by using MAXScript. The Python integration also exposed a new intermediate API in 3ds Max called MaxPlus. MaxPlus for Python 9
is implemented as a CPython extension and exposed parts of the C++ SDK functionality to the Python environment. There are three ways to execute Python in 3ds Max: Executing files from MAXScript python.executefile demohelloworld.py Execute code from MAXScript: python.execute print hello world! Execute file from command-line: 3dsmax.exe U PythonHost demohelloworld.py Working in the Python environment 3ds Max is not providing any helper tools to write and debug python. Products like Maya include a Python console and editor, however, 3ds Max is not doing this. But because Python is such a widelyused environment, there are other tools that you can setup to use with 3ds Max. For example, the PyCharm editor and debugger is an excellent choice. This tool is available from here: http://www.jetbrains.com/pycharm/download/index.html. PyCharm also has remote debugging capabilities that allows you to step through code and do typical debugging activities use features like break-points. The Python output is directed to the MAXScript window, so you can already see how tightly integrated it is with MAXScript. See the samples in the python folder. Additional Resources for using Python: 3ds Max help: Python Help Autodesk Forums: 3ds Max Programming ADN DevTech team is providing Python support. Python samples included with 3ds Max: <Install location>\3ds Max 2016\scripts\Python Blog: http://getcoreinterface.typepad.com 10
What is.net API? The 3ds Max.NET API story started with release 2008. The Microsoft.NET Framework has become a popular choice among programmers. Other Autodesk products like AutoCAD and Revit have robust.net API environments. 3ds Max started out with a series of assemblies that were mainly designed to help provide more robust user interface experiences to 3ds Max. With the release of the Subscription Advantage Pack (SAP) in 2012, 3ds Max included a full.net API wrapper assembly that provides a 1-to-1 mapping of the 3ds Max C++ SDK libraries. With this enhanced API, the intention is to allow enhanced automation functionality, but not support full plugin development. The.NET API assemblies provided with 3ds Max allows you to code in the managed languages you want, such as C#, VB.NET, or C++/CLI (managed C++). The.NET API is provided as a set of assemblies that you consume to program 3ds Max. These assemblies provide functionality and wrappers directly into the internals of 3ds Max. If you do not have a language preference already, it is suggested to use C#. This has become the most popular managed language and you will find many samples using this syntax already. Why would you use the 3ds Max.NET API? The.NET API has been a very popular windows based technology. It is a very friendly environment that provides basics concepts like reflection (easy to see the APIs through the fundamental design of the framework itself)..net API is an obvious choice if you are coming from another.net oriented environment, like AutoCAD or Revit. However, note that the main API assembly, Autodesk.Max.dll is an auto-generated wrapper of the C++ SDK functionality. As such, the API is not always easy to use and can contain some mal-formed APIs. How to use the 3ds Max.NET API? The.NET API assemblies are located in the 3dsmax.exe installation folder. There is online documentation for the 3ds Max SDK here: 3ds Max.NET SDK. Also because the.net API main components are based on the C++ SDK it is a good idea to use those docs to understand the fundamental techniques of the SDK. Installing the SDK itself is not necessary, but it can also help through showing C++ examples that you may want to review for repurposing in the.net API environment. The supported API assemblies are listed below: Autodesk.Max.dll - Contains wrappers that expose most of the API elements from the 3ds Max C++ SDK to.net constructs. Currently it is not recommended to derive from the Autodesk.Max.Plugins classes. AssemblyLoader.dll - Contains the Loader class. CSharpUtilities.dll - Various utility classes for.net programming. ExplorerFramework.dll - Abstract explorer framework classes upon which the Scene Explorer is built. It can be used for creating a new node traversal for arbitrary scene explorers. ManagedServices.dll - Exposes some convenient 3ds Max SDK functionality to.net. MaxCustomControls.dll - Various.NET utilities and UI components. SceneExplorer.dll - Specification of the ExplorerFramework components for the SceneExplorer with bindings to 3ds Max data. UiViewModels.dll - Contains classes for defining user actions and customizing the user interface. 11
See the samples in the dotnetapi folder. Additional Resources for 3ds Max.NET API 3ds Max SDK Documentation: 3ds Max.NET SDK. There is additional information in the "Learning Path" section that include a.net API example. Autodesk Forums: 3ds Max Programming ADN DevTech team is providing.net API support. Blog: http://getcoreinterface.typepad.com 12
What is the 3ds Max C++ SDK? The 3ds Max SDK provides the most robust way of programming 3ds Max functionality. In fact many of 3ds Max s own features are developed using the SDK functionality. It is used for sophisticated plug-in development and is comprised of C++ object oriented libraries. The SDK is provided as a separate installation. Why would you use the 3ds Max C++ SDK? There is functionality available for almost everything. This programming facility provides the widest and most flexible access to 3ds Max functionality. It is very flexible and provides the ability to modify or change existing behaviors. The SDK itself includes many sample, and some are the exact same as the 3ds Max feature. For example, the complete source code of the Bend Modifier is provided completely as sample source code. As a commercial developer the C++ SDK would be your main choice. Because it is native C++, your resulting plug-in is a fully compiled binary DLL. Functionality is very far reaching and includes this list: 3D Texture Map Animation Controllers Atmospheric Bitmap Texture Camera Object Color Selection Compound Objects Crowd Behavior File Export File Import Geometric Objects Global Utility Hardware Shaders Image Filters Image Import/Export Image Viewers IK Solver Helper Objects Light Objects Linear Shape Object Manipulator Objects Material Plug-in MAXScript Extensions Modifier Multi-pass Camera Effects Particle Objects Patch Objects Radiosity Effect Renderer Rendering Effects Render Elements Sampler Shader Shape Objects Snaps Sound Spline Objects Spring Systems Texture Map Track View Utility Utility World Space Modifier How would you use the 3ds Max C++ SDK? Install the SDK from 3ds Max media AFTER 3ds Max itself is finished. The main installer includes the SDK as a tools option, but you can also install it directly. You can find the SDK MSI installer here: <media location>\x64\tools\maxsdk 13
For 3ds Max 2015/2016, you will need Visual Studio 2012. You need C++ 11.0 Service Pack 3. Visual Studio 2012 Update 4. The Visual Studio IDE itself is not important, so you can use newer versions of Visual Studio. However, it is CRITICAL for binary compatibility that the build toolset be set as Visual Studio 2012 (v110). This is accomplished simply by having the C++ compilers installed side-by-side. There is a Plug-in Wizard for Visual Studio that can create skeleton code for many of the main plug-in types. Many samples are provided, and I would encourage you to review the samples to determine if the functionality you want to implement is already partially done. Note that some of the samples are using older, but still supported techniques. For example, the IParamBlk2 is the most current way or storing data for your plug-in, but some of the older plug-ins are using older versions of this mechanism. Make sure to use newer techniques when possible. See the samples in the MaxSDK folder. Additional Resources for learning 3ds Max C++ SDK The documentation for the 3ds MAX C++ SDK is very mature and is the best place to start. Additionally, because the 3ds Max SDK has a long history, there are many resources on the web that can help. The ADN DevTech team s primary goal is to support the 3ds Max SDK. We will help with 3ds Max SDK programming issues and have direct access to the 3ds Max engineering team. If you are interested in developing a commercial or sophisticated internal plug-ins, ADN can help with direct support and development licenses of all Autodesk software with APIs. 14
Get KUDOS! The Autodesk 3ds Max Programming Forums Normally having presence on any social or community network, and showing yourself as an expert is a way to gain distinction as an expert. For 3ds Max programming, there is one location on the Autodesk community forums that would help in this endeavor. Simply answering questions in the 3ds Max programming forum, about any of the customization topics we have discussed, will gain you kudos. http://area.autodesk.com/forum/autodesk-3ds-max/programming Using the Autodesk forums not only give you expert distinction, but also gamified kudos that you can collect: For more information, see: http://forums.autodesk.com/t5/help/faqpage/faq-category-id/kudos 15
The Autodesk App Store KUDOS == Fame and Fortune? Not always, but in addition to being known as an expert, you can also gain fame and fortune by publishing your experience through the Autodesk App store. Apps can be free, trial, or for fee. The App Store is a good way to bring awareness to you or your company. For example, it could be a nice place to show your skills if you are also a consultant. Here are the fundamental steps to publish to the Autodesk App Store: 1. Build your App! This is the hardest part. 2. Build the structure for the App Store requirements. This means making sure it is easily found in the UI, and if your tool does not already have UI entry, our guidelines can help you to define one. 3. Go through the publisher steps at the App Store. 4. Sit back and bask in the in fame and fortune! Resources to help: Autodesk Exchange Apps - Information for 3ds Max http://usa.autodesk.com/adsk/servlet/item?siteid=123112&id=22224468 Defining Macro Scripts http://docs.autodesk.com/3dsmax/14/enu/maxscript%20help%202012/index.html?url=files/guid- 6E21C768-7256-4500-AB1F-B144F492F05-1819.htm,topicNumber=d28e624900 Pre-defined menu to guarantee uniqueness http://docs.autodesk.com/3dsmax/14/enu/maxscript%20help%202012/index.html?url=files/guid- 258F6015-6B45-4A87-A7F5-BB091A2AE06-1937.htm,topicNumber=d28e658011 Localization strategies for 3ds Max Plug-ins http://around-the-corner.typepad.com/adn/2013/06/localization-strategies-for-3ds-max-plugins.html ADN-ExplodeGeometry This is a sample plugin from the store that you can install and run as-is. But located in our github repo is the complete source code. See here: https://github.com/adn- DevTech/3dsMax-Explode-Geometry/ 16
3ds Max Customization Summary General Customization UI Customization is easy and low investment of time/money Allows for easy in-house standards/customization UI customization is often needed for plug-in exposure, toolset, etc. Max Creation Graph is a new visual programming environment allowing easy creation of plugin style tools Max Creation Graph is not meant for a commercial application, and is an interpreted environment. It currently does not support the Autodesk App store. MAXScript Easy to get started and low investment of time/money Powerful, but is a proprietary language Tools are fully supported in the Autodesk App Store Python Easy to get started and low investment of time/money Python is a popular and common language and has many libraries that can be consumed Good if you want to have interop with other environments, or existing python based pipelines/workflows. Tools are fully supported in the Autodesk App Store (because they load via MAXScript).NET API Useful for UI or consumption of other.net Framework functionality Full managed wrappers matching C++ SDK, meant for automation programming Not a well formed managed API and follows many C++ style programming techniques. Tools are fully supported in the Autodesk App Store 3ds Max C++ SDK Requires serious programming skills in C++ 17
The most powerful and flexible customization capabilities Consider for commercial or complex functionality Consider maintenance overtime since it will need to be recompiled from time-to-time to match the 3ds Max binary requirements. Tools are fully supported in the Autodesk App Store Kudos The Autodesk 3ds Max programming forum is a great way to share and show your experience Use the Autodesk App Store as a great way to share your tools and maybe get Fame and Fortune? 18
Resources for 3ds Max Customization 3ds Max Developer Center: www.autodesk.com/develop3dsmax The following resources have customization topics for 3ds Max. Blogs: http://getcoreinterface.typepad.com http://area.autodesk.com/blogs/chris Autodesk AREA http://area.autodesk.com/ http://area.autodesk.com/forum/autodesk-3ds-max/programming http://www.gamedev.net http://www.cgsociety.org Information about Autodesk Developer Network (ADN): www.autodesk.com/adn and www.autodesk.com/adnopen 19