Scripted Plug-ins
MAXScript supports several levels of scripted plug-ins, as follows:
Level 1 Scripted Plug-in
The scripted plug-in appears in the user interface as a new class but does not allow instances of itself in the scene. It lets you define a mouse tool that creates other objects in the scene, but once you've finished creation, there is no instance of the class left in the scene to modify or save. Examples of this currently in 3ds Max are the System classes such as RingArray.
Level 2 Scripted Plug-in
The scripted plug-in extends an existing plug-in, either adding to or replacing the command panel parameter rollouts for the existing plug-in. For example, you might create a new "glass" material which extends StandardMaterial and provides a custom, presumably smaller, Material Editor rollout that just has glass parameters which set up and modify various properties in the underlying material plug-in as appropriate. Or, you want to create a new light type that is actually a system of coordinated lights, that also has a "controlling" dummy object created. This controlling dummy keeps track of the lights in the system and has a Create/Modify panel rollout that allows coordinated manipulation of the system. In this case, you'd create a new helper plug-in that extends Dummy, has locals to store the lights, and define a rollout. You would also create a new light plug-in with a create tool that builds the system.
Level 3 Scripted Plug-in
The scripted plug-in is given a unique and permanent class ID value by the script writer and so can be instanced in the scene and stored in scene files. All 3ds Max plug-ins have a unique class ID and 3ds Max uses this class ID to associate stored scene objects with the code that handles them each time you open a scene file, hence it has to be unique and permanent. In the level 1 scripted plug-in above, MAXScript allocates a temporary class ID that is not permanent across executions of 3ds Max and thus prevents instancing in the scene.
Level 4 Scripted Plug-in
The scripted plug-in defines one or more parameter blocks, containing directly animatable parameters that are saved to and restored from scene files. These are the permanent parameters for the plug-in and are distinct from the local variables in the example above which only live during creation.
Level 5 Scripted Plug-in
A parameter block can be associated with a rollout in the scripted plug-in that provides a user interface for the parameters in the parameter block. When associated in this way, the parameters are "wired" to their spinners and checkboxes, etc., and both update automatically as the other changes.
The general form for a scripted plug-in is:
<superclass> is one of the currently supported plug-in superclasses:
Geometry SimpleObject Shape Light Camera Helper Modifier SimpleMod TrackViewUtility Material TextureMap RenderEffect Atmospheric
<varname> is the name that will be given to the global variable that contains this plug-in class. This class value is just like a normal plug-in class (like box, sphere, etc.) and you can create an instance of the plug-in in MAXScript by applying the class value.
{keyword:val} is an optional sequence of keyword/value pairs defining options for the plug-in. These pairs are:
The optional name: parameter specifies the name of the plug-in as seen in the 3ds Max user-interface. For example, if the superclass of the plug-in is geometry or light , this name would be displayed on the plug-in’s button in the Create panel; if the superclass of the plug-in is modifier , this name would be displayed on the plug-in’s button in the Modify panel; and if the superclass of the plug-in is material or textureMap , this name would be displayed in the Material/Map Browser. The default name is the plug-in’s <varname>.
In versions prior to 3ds Max 2014, the name: parameter was used to define the naming of class instances and scene objects. This changed in 3ds Max 2014 - the <varname> will be used to define the name of class instances and scene objects, the name: parameter will be used only for the (localizable) creation buttons/entries in the UI.
For example, a scripted geometry plugin with <varname> myCuboid and name:"Supa Cuboid" will display "Supa Cuboid" on its creation button, but the Modifier Stack will show a base object called "myCuboid" and the scene node will be named "myCuboid001". In earlier versions of 3ds Max, the Modifier Stack was showing "Supa Cuboid", and the scene node was named "Supa Cuboid001".
The optional category: parameter specifies in which object category (access via the object category list) the plug-in will appear in. This parameter is applicable only to plug-ins that appear in the Create panel. The default category in "Standard". Note that there is a fixed number of buttons available in the Create panel for each category. If a button for your plug-in does not show up in the appropriate Create panel, you may need to make a new category for it.
You supply the classID:#(<integer>,<integer>) parameter if you want the plug-in to be creatable and storable in the scene. This ID becomes the permanent ID for the class and is used by 3ds Max to identify objects as they are saved and loaded in the scene. You don't need to supply a class ID value if the plug-in is to be like a System object that only creates other types of objects in the scene. The class ID is basically a pair of numbers, chosen randomly so that (hopefully) they won’t conflict with another plug-in. MAXScript provides a method to generate a fresh random class ID each time you run it:
This method generates a random class ID similar to #(0x9b7ea231, 0xb6db86ef), and prints it by default to Listener. You can cut and paste this class ID into your script to use the generated ID.
In 3ds Max6 and higher, if returnValueL is true , the classid is not printed to the Listener, rather a 2 element array containing the 2 parts of the class ID is returned.
The extends:<maxClass> parameter is supplied if you want to base your plug-in on an existing plug-in. This basically lets you add a new class that works internally exactly like the one you are extending, but with an expanded or replaced user interface. The class you specify must have the same superclass as specified in the scripted plug-in header. Current limitations prevent certain plug-ins from being extended, in particular those with custom creation managers. These include target lights and cameras and all the System plug-ins. You can tell if a plug-in is not extendable if your new rollouts do not appear.
When you create an object of scripted plug-in that extends another, MAXScript also creates an internal object of the extends: plug-in and passes most of 3ds Max's interaction with your plug-in onto the internal object. This is called delegation and the internal extends: plug-in object is the delegate. The delegate is visible in your plug-in's objects in Track View and you can access the delegate in your scripts to control it as needed. See the locals section below for more information. The delegate is not shown in TV if replaceUI:true is specified.
The replaceUI: parameter is used only when extends: is supplied to indicate whether the rollouts in your plug-in should add-to or replace the extended plug-ins rollouts. The default is false , which means your rollouts will be appended at the end of the extended plug-in's. Another current limitation when extending plug-ins whose objects are created in the Create panel only allows user interface replacement in the Modifier panel; the original plug-in's rollouts are always displayed along with the scripted rollouts in the Create panel.
The optional version: parameter specifies the version number of the scripted plug-in. The value assigned to this parameter is used when updating the scripted plug-in definition. The default value for this parameter is 1. See Updating Scripted Plug-ins for more information on this parameter.
The optional invisible: parameter gives control over whether the plug-in is visible in the Create panel Object Type rollout or in the Material/Map Browser, etc. This is useful for component or controlling objects created as part of a group, say in a System-style plug-in that should not be creatable on their own. Set this parameter to true to hide the plug-in.
The optional silentErrors: parameter gives control over whether MAXScript run-time error messages are displayed when executing handlers in the scripted plug-in. If this parameter is set to true , error messages will not be displayed. This may be useful for distributed scripted plug-ins that may confuse the user with MAXScript error messages.
usePBValidity:<boolean>
The optional usePBValidity: parameter is applicable to scripted plug-ins that extend an existing class. If usePBValidity is false (the default, which matches the original behavior), the validity interval of the scripted plug-in does not include the validity of controllers in the scripted plug-in, only the validity of the delegate that is used. If true, the validity interval is the intersection of delegate's validity interval and the validity interval of any parameter blocks defined in a scripted plug-in.
Available in 3ds Max 6 and higher.
The argument is an integer whose 32 bits are used to initialize the rollouts' rollup state in both the create and the modify panel. The semantics are different, however for these two cases. Whenever the rollups are created in the create tab, their state will be that specified by this value. In the modify tab, the first time an object of this type is modified, the state will be that of this value, after that it will remain what it was last set to. The bits of this value indicate the corresponding rollout page is rolled up (closed). The zero bit corresponds to the plug-ins first rollout, the first bit is the second rollout, etc. The default value of 0x7fffffff is used so the command panel can detect that this value is not being overridden, and just leave the rollouts as is. For example, a value of 0x07 would result in the first 3 rollouts being rolled up, and the remaining rollouts open.
In 3ds Max 6 and higher, the optional autoPromoteDelegateProps : parameter gives control over whether the delegate’s properties are automatically searched if a property access is performed on the plug-in, but the property is not defined by the plug-in. Defaults to false .
This keyword allows parameter names in the definitions to be changed when updating existing definitions.
The keyword takes as an argument a 2 element array, where each element contains an array of string literal or name values. The size of the 2 arrays must be the same.
The names in the first array are the existing parameter names, the names in the second array are the new parameter names. As parameter names are read in while migrating existing plugin instances, the parameter names are searched for in the first array. If the name is found, the data associated with that parameter is moved to the parameter name in the corresponding location in the second array. If a parameter name is not found in the first array, the parameter name is not remapped. If the parameter name in the second array does not match a parameter name in the new definition, the parameter data is not moved to the new definition.
<plugin_body> is enclosed in the required parentheses and is a sequence of clauses that define the local variables and functions, parameters, user-interface items, and event handlers that define the plug-in. These clauses are defined in detail in Scripted Plug-in Clauses.
If you load a scene file that uses a level 3 or higher scripted plug-in, and you have not defined that scripted plug-in, a Missing DLL dialog will be displayed after the load, indicating the definition for the scripted plug-in is missing. The file will then load using a standin for the object with the missing definition, just as it would for other objects missing their DLL definitions. 3ds Max treats scripted plug-ins as it does C++ plugins, requiring the definition to be in place, either in a script file in the plugins directory when 3ds Max starts, or having been defined by running some script prior to loading the file.
See Also
Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Please see the Autodesk Creative Commons FAQ for more information.