Scripted Plug-ins

MAXScript supports several levels of scripted plug-ins, as follows:

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.

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.

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.

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.

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:

plugin <superclass> <varname> {keyword:val}

( <plugin_body> )

where:

<superclass> is one of the currently-supported plug-in superclasses:

Geometry

SimpleObject

Shape

Light

Helper

Modifier

SimpleMod

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:

name:<string>

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>.

category:<string>

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.

classID:#(<integer>,<integer>)

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:

genClassID()

This method generates a random class ID similar to #(0x9b7ea231, 0xb6db86ef), and prints it to Listener. You can just cut and paste this class ID into your script to use the generated ID.

extends:<maxClass>

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.

replaceUI:<boolean>

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.

version:<integer>

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.

invisible:<boolean>

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.

silentErrors:<boolean>

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.

<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.