Updating Scripted Plug-ins

MAXScript allows you to redefine scripted plug-ins while working in 3ds Max, and have old instances in the current scene and in scenes you load automatically update to the new definition. This ability to redefine scripted plug-ins is called schema-migration. MAXScript does this by matching the names of local variables, parameter blocks, and parameters between the old version instances and the new definition. It keeps any variables, parameter blocks, and parameters of the same name, drops anything missing in the new definition and creates new variables, blocks, and parameters as needed, filling them in with default values.

There are some limitations on the kinds of change that can be supported. Specifically:

• Parameter blocks that were per-instance cannot be made per-class and vice versa.

• Parameters cannot change type across redefinitions.

• Parameters cannot move from one parameter block to another across redefinitions.

This same mechanism is used to update old versions of scripted plug-in objects stored in scene files. Remember that this only works if the classID: specified in the scripted plug-in definition that was in force when the scene was saved is the same as the current classID: in the definition as 3ds Max depends upon this classID to match objects in the scene file and their class definitions.

You can specify an update event handler in a scripted plug-in and it will be called whenever the object is updated by this schema migration mechanism. To make this more useful, MAXScript supports a version number on scripted plug-ins. The version for any particular instance of the plug-in can be accessed using the version special local variable in any plug-in local function or handler. When the update event handler is called during a schema-migration, the old version number is still in force, but is updated to the current version number immediately after update.

plugin helper lightMaster
name:"Light Master"
classID:#(12345,54321)
extends:Dummy
invisible:true
replaceUI:true
version: 3 -- set current version to 3
(
parameters main rollout:params
...
on update do
(
if version == 1 then ... -- do something special for v1 instances
)
...
)

An optional remap: keyword introduced in 3ds Max 7 allows parameter names in the definitions to be changed when updating existing definitions.

The keyword takes as an argument a two element array, where each element contains an array of string literal or name values. The size of the two arrays must be the same.

The names in the first array are the existing parameter names and 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.

Finally, if there are no existing instances of the plug-in, either in the current scene or in other scenes, you can simply delete them and make whatever changes you like in the scripted plug-in definition. The above version update considerations come into play only when you wish to support old version objects of your scripted plug-in.