The Procedural Clip (runtime structure) and Procedural Clip Parameter (static data structure) have gone through some structural changes in order to fix some of their shortcomings.
The Procedural Clip Parameters in the old format consisted of a fixed number of strings and floats. With the new format, implementers of Procedural Clips have control on the types, names and the number of parameters that they require, and on how those are presented to the user in the UI. This is achieved by having each Procedural Clip define the specific structure that it requires for its parameters.
Projects updating to this Mannequin version must update their code and data structures. See Overview of Required Work for Conversion to New Structure for more detailed information.
The Serialization Library is used to serialize Procedural Clip Parameters both to disk and to the UI. For this to work, we must write a Serialize function for the Procedural Clip Parameter structure.
The ProcDefs.xml file is no longer needed.
The xml format for ADB files has changed. Some remarks:
- It is possible to load old ADB files. For loading ADB files saved in the old xml format a conversion file is necessary (See Example of Data Conversion from Old Procedural Clips to New Procedural Clips for more details)
- It is not possible to save to the old xml ADB format any more.
Procedural Clips and Procedural Clip Parameters don't use CryExtension. Both structures are created through the ProceduralClipFactory, accessible via the main MannequinInterface.
Comparison of Old Procedural Clip Parameter and New Procedural Clip Parameter Structure
Old Procedural Clip Parameters structure consisted of a string, a string+crc32, a crc32 of a string, and and array of around 30 floats.
All Procedural Clips inherited from SProceduralParams and defined the floats variables they used, limited in number by the amount of floats specified in SProceduralEntry.
The initial values of the members were defined in ProcDefs.xml when we created a proc clip that used this parameter type.
As of the new version, SProceduralParms doesn't exist anymore.
We must inherit from the IProceduralParams interface, implement the Serialize function.
We initialize the values of the members in the constructor.
We don't require the ProcDefs.xml file anymore.
We are not restricted to just using floats or the amount/types of strings we have, and we can give all members meaningful names.
Overview of Required Work for Conversion to New Structure
Update code structures
It is necessary to change the code to update Procedural Clips Parameters structure and how Procedural Clips get registered with the system.
For more details see the following sections:
- Comparison of Old Procedural Clip Parameter and New Procedural Clip Parameter Structure
- Example of Code Conversion from Old Procedural Clips to New Procedural Clips
Update animation databases
Create the "ProcClipConversion.xml" file.
- This allows to load databases saved in the old format into the new one.
Load the animation databases in the editor and save them again.
- This is a one time only operation, so it's important to check thoroughly that data conversion was successful.
- Double check the errors/warning in the log when loading and saving the animation databases.
- Double check the xml differences to make sure nothing went wrong.
- It's not possible to save into the old Procedural Clip format again.
- Once everything is converted "ProcClipConversion.xml" is not needed anymore.
For more details see the following section:
Example of Code Conversion from Old Procedural Clips to New Procedural Clips
Procedural Clip Parameters
The Procedural Clip Parameters structure becomes:
To implement the Serialize function we must include the Serialization Framework.
We can also give some hints to the Serialization Framework on how to present our attributes in the UI by using decorators.
The following shows how to have the Animation property display an Animation Browser and to limit the AnimationLayer to values between 0 and 15.
You can find more information about the serialization function here: Serialization Library.
Procedural Clip and Registration
The Procedural Clip and its registration are also simplified a bit, by not requiring the CryExtension GUID anymore.
Example of Data Conversion from Old Procedural Clips to New Procedural Clips
To be able to read animation databases that were created when using the old Procedural Clip format, we have a helper class that will allow to load old Procedural Clips if we specify a mapping from the old parameter format to the new parameter format.
The mapping is defined in:
This file is used while loading when we encounter an old Procedural Clip type. It works on all platforms to make the transition from old data to new data as seamless as possible until the animation databases are upgraded by re-saving them in the editor.
This is how the format of the ProcClipConversion.xml file looks like:
Values for parameter names in ProcClipConversion are the serialized parameter names in the Serialize function.
This is how it would look like to convert automatically from old AimPose Procedural Clip parameters to the new format.
This structure can easily be obtained through some minor modifications to the ProcDefs.xml by filling in for each parameter the names that we use them
For reference, this is how the ProcDefs.xml entry for AimPose looked like:
And also for reference, this is how the Serialize function looks like:
When converting old Procedural Clip Parameters via this method, the log will get filled with messages similar to the following:
Warnings and errors will be logged in cases where the conversion fails, so it's important to check the log before saving the files as conversion might have failed. Clips that fail to convert become "None" clips.
It is ok to ignore the converter failing when encountering an old Procedural Clip of type "None", since that becomes a "None" clip in the new format. The error message will look like this: