Share

.maxtool Files

A .maxtool file acts as the entry point for defining a new MCG tool within 3ds Max.

Tool Inputs

The inputs of a tool must be declared as Tool Input nodes (Inputs > Tools). Every tool input will appear as a UI element in the tool's rollout.

Tool Outputs

The terminal Output node of a .maxtool file defines the type and location of the tool within 3ds Max. The output nodes are listed in the table below, and under the Outputs > Tools category in the Operator Depot.

Certain tool types accept specific input nodes in order to define incoming data. These inputs are listed in the Special Inputs column, and under the Inputs > Tools category in the Operator Depot.

Output Special Inputs Default Location
Output: Geometry Geometry: Local to World Matrix Create Tab > Geometry > Max Creation Graph
Output: Spline Spline: Local to World Matrix Create Tab > Shapes > Max Creation Graph
Output: Modifier Modifier: Mesh, Modifier: Bounding Box, Modifier: Local to World Matrix Modify Tab > Modifier List
Output: MAXScript Function - MAXScript Listener or MAXScript Editor
Output: Utility - Utilities Tab > MAXScript > Utilities Drop-Down List > Tool Rollout > Execute
Output: Transform Controller Transform Controller: Parent Matrix Motion Tab (or Track View) > Select Transform Track > Assign Controller
Output: Position Controller - Motion Tab (or Track View) > Select Position Track > Assign Controller
Output: Rotation Controller - Motion Tab (or Track View) > Select Rotation Track > Assign Controller
Output: Scale Controller - Motion Tab (or Track View) > Select Rotation Track > Assign Controller
Output: Float Controller - Motion Tab (or Track View) > Select Float Track > Assign Controller - or - Material Editor > Material/Map Browser > Controllers > Float Controller
Output: Color Controller - Motion Tab (or Track View) > Select Point3 or Color Track > Assign Controller - or - Material Editor > Material/Map Browser > Controllers > Point3 Controller
Output: Point3 Controller - Motion Tab (or Track View) > Select Point3 Track > Assign Controller - or - Material Editor > Material/Map Browser > Controllers > Point3 Controller
Output: Point4 Controller - Motion Tab (or Track View) > Select Point4 Track > Assign Controller - or - Material Editor > Material/Map Browser > Controllers > Point4 Controller

Saving and Evaluating

To use a new MCG tool in 3ds Max, it must first be saved (File > Save/Save As... or CTRL+S) then evaluated (Build > Evaluate or CTRL+E). The first time you save a tool, the Graph Properties dialog will appear (see below). The location of the saved .maxtool file affects how it is loaded on startup:

  • Saving a .maxtool to the default location C:\Users\username\Autodesk\3ds Max 2018\Max Creation Graph\Tools will make it appear when 3ds Max starts up. See here for more information on customizing the MCG loading path.

  • Saving a tool outside the MCG loading path will only make this tool available during the current session of 3ds Max; it will not be loaded automatically when 3ds Max starts up. To continue iterating on a .maxtool file outside the loading path, it must be opened in the Max Creation Graph editor and evaluated (CTRL+E).

To evaluate all the tools (and packages) in the MCG loading path manually, select Build > Evaluate All Tools and Packages.

.ms and .txt Files

When a .maxtool file is evaluated, two files are generated with it. These files are not required for the proper functioning of the tool, and only exist for viewing purposes. If 3ds Max does not have write permissions in the directory, these files will not be generated (the tool will nonetheless run correctly).

  1. A MAXScript file (.ms) is created to view the MCG plugin's boostrapping code. The rollout portion of this graph can be copied into the Custom UI tab of the Graph Properties to fine-tune the layout of the tool's user interface. For more information on customizing the rollout, see here.

  2. A text file (.txt) is created to represent the flattened call structure of your graph, and to locate any errors printed in the listener. The variables and expressions in this file are labeled according to the node ids in the editor.

Note:

.mcg packages and .maxcompound files do not generate .ms or .txt files.

Graph Properties

When you save a new tool (File > Save As...), you are prompted with the Graph Properties dialog. This dialog may also be accessed under Edit > Edit Graph Properties.... Changes made to this dialog are applied upon saving (by pressing Save As upon first save, or by pressing OK then CTRL+S if the graph was already saved once).

Tool Name

A tool name is valid if it does not conflict with any of the tool names which are currently loaded into 3ds Max. You will be presented with an error in the MAXScript Listener if the tool's name conflicts with a pre-existing tool.

Note: Redefining a tool's name may have unexpected consequences if the tool is active your scene. If you are modifying a tool's name, it is recommended you restart 3ds Max.

Graph GUID

This value is ultimately responsible for defining the unique 3ds Max plugin class ID associated with this tool. Every MCG tool is registered into 3ds Max via the plugin system. When a new .maxtool file is saved for the first time (File > Save As...), the Graph GUID will be automatically generated. You may inspect this graph GUID by re-opening the Graph Properties dialog (Edit > Edit Graph Properties...) once the file has been saved.

Given the interactions with the 3ds Max plugin system, there are a few points to keep in mind when manipulating .maxtool files on your filesystem:

  • If you copy a .maxtool file and rename it, a duplicate message will be displayed in the MAXScript Listener if both these files exist in the MCG loading path on startup. Despite having a different filename, both files will contain the same Graph GUID. The highest version of a tool will be built if duplicate Graph GUIDS are found.

  • The Graph GUID may be modified manually by opening the .maxtool file in a text editor, and editing the guid attribute in the <graph_version guid="..." number="..."/> XML element. CAUTION: Modifying this value will break all the scenes which depend on this tool; the 3ds Max plugin classID is ultimately altered by modfying the Graph GUID.

Version

  • Major, Minor: These fields may be incremented manually. We recommend Semantic Versioning for your tools and compounds.

  • Revision: This field is incremented automatically every time the file is saved.

  • Version GUID: A unique GUID generated every time the file is saved.

Display Name

The label associated with your tool in the 3ds Max interface. Only applies to the following tool types:

  • Geometry and Spline: affects the button label in the Create Tab.

  • Modifier: affects the label in the Modifier List.

  • Controller: affects the label in the Assign Controller dialog.

Category

The custom location of the tool. Only applies to the following tool types:

  • Geometry: Create Tab > Geometry > Custom Category

  • Spline: Create Tab > Shapes > Custom Category

  • Modifier: Modify Tab > Modifier List > Custom Category

Note:

To view the custom category in the modifier list, you must right-click on the Modifier List and enable Show All Sets in List.

These fields along with the Category and the Version appear in the MCG package installation browser once the .maxtool has been packaged as a .mcg file.

Is Simulation

When enabled, modifies the evaluation of the tool to ensure the timeline's playback is consistent with an internally cached simulation state. Also ensures that all caches in the tool are reset when the Reset Simulation button is pressed in the rollout, or if the timeline is set back to frame 0.

Note: For best results, if you are using a simulation tool in your scene, ensure the Real Time option is disabled in the 3ds Max Time Configuration dialog such that every frame is processed.

When disabled, removes the Open in MCG Editor button from the tool's rollout menu. If the tool is packaged, this button will not appear regardless of the option chosen.

File, Created, Last Modified

The filepath and the dates at which the file was created and modified.

Parent page: File Management and Packaging
Previous page: MCG File Types and Loading Paths
Next page: .maxcompound Files

Was this information helpful?