Guidelines for Changing Parameter Descriptors

• Use the P_VERSION flag and update the version number when changing the parameter block descriptor.
• Do not change the parameter block descriptor ID or owner reference ID.
• Do not change the type of an existent parameter.
• You may add a new parameter of the desired type at the end of the list of parameters and mark an old one obsolete using P_OBSOLETE .
• Do not change parameter IDs.
• Do not delete or move items in the enum defining the parameter IDs. Instead, add new parameter IDs at the end of the enum.
• Do not change the animatable state of a parameter (i.e. do not add or remove the P_ANIMATABLE flag). Instead, mark the old parameter as obsolete and create a new parameter at the end of the parameter list with the desired animatable state.
• You may add - but not remove or change - any of the following flags: P_NO_REF, P_OWNERS_REF , P_TRANSIENT , P_SUBANIM , P_READ_ONLY , and P_OBSOLETE.
• Non-animatable, and non-reference parameters can be added anywhere in the parameter block descriptor. Reference parameters are: TYPE_MTL, TYPE_TEXMAP, TYPE_INODE, TYPE_REFTARG, TYPE_PBLOCK2, TYPE_OBJECT, and TYPE_CONTROL, along with the corresponding TAB version. Animatable parameters are marked with P_ANIMATABLE.

Guidelines for Saving Plug-ins

• Use ISave::SavingVersion() or ::GetSavingVersion() function to determine which Max file format is used for saving your data.
• Adding a new chunk should be fine if your plug-in ignores unrecognized chunk IDs in its implementation of ReferenceMaker::Load().
• Removing an existent chunk is not acceptable.
• Be prepared to save out the data corresponding to the old chunk ID when 3ds Max signals that it is saving the file to a format compatible with a previous version of 3ds Max. The plug-in must call ISave::SavingVersion() to find this out.
• Changing the contents of an existent chunk is best handled as an addition of a new chunk and deprecation of the current chunk (e.g. ignoring it on load).

Animatable Structure Change Guidelines

You cannot change the sub-animatable structure of a plug-in and support save to previous. There's currently no general way to inform the previous release of what the new mapping is. Therefore, anything that depends on sub-animatable numbering (e.g. expression and wire controllers) will most probsbly crash or at least will not work properly.

Copying a Parameter Block 2 to a Parameter Block 1

When a plug-in is migrated from using parameter block 1 (class IParamBlock) to using parameter block 2 (class IParamBlock2) two responsibilities are particularly important:

The plug-in must support loading parameter block 1 versions of itself. This task is facilitated by the already-existing global function: IParamBlock2* UpdateParameterBlock2(ParamBlockDescID *pdescOld, int oldCount, IParamBlock *oldPB, ParamBlockDesc2* pdescNew, IParamBlock2* newPB);

The plug-in must also support saving parameter block 1 versions of itself (for supporting the save to previous functionality of 3ds Max). This task is facilitated by the following global function: int CopyParamBlock2ToParamBlock(IParamBlock2* pb2, IParamBlock *pb1, ParamBlockDescID *pdescPB1, int pb1Count);

Although parameter block 1 based plug-ins are still supported in 3ds Max, plug-in developers are encouraged to migrate their plug-ins to use the parameter block 2 system.

The Swirl plug-in is an example of a plug-in that uses these APIs to save a parameter block 1 based version of itself to previous versions of 3ds Max, while maintaining support for loading its old parameter block 1 version.