SDK Compatibility with Cubism 5 Features
Updated: 08/17/2023
This page contains statements regarding the beta version.
Summary
This section describes the following points about SDK compatibility with Cubism 5.
- What changes were made in the 5 SDK?
- What notes or changes are needed for compatibility with the existing 4.2 SDK?
About the Names
4.2 SDK refers to Cubism 4 SDK R7 and earlier.
5 SDK refers to Cubism 5 SDK R1 beta1 or later.
Table of new features in Editor 5 and their support by the 5 SDK
5 Editor new features | SDK support [support date] |
|---|---|
| Enhanced Blend Shape | 〇 Supported (from beta1) |
| Motion-sync | △ Supported (Unity only from beta1) |
| Support for switching between Dark and Light themes | No SDK support, as this is Cubism Editor functionality. |
| Support for HiDPI displays | No SDK support, as this is Cubism Editor functionality. |
| Custom Workspace | No SDK support, as this is Cubism Editor functionality. |
| Environment Settings dialog box | No SDK support, as this is Cubism Editor functionality. |
| Improved accuracy of automatic mesh generation | No SDK support, as this is Cubism Editor functionality. |
| Auto generation of facial motion | No SDK support, as this is Cubism Editor functionality. |
Fixes affecting compatibility
- Fixing bugs with expression transition processing
- Change in class structure of Renderer-related processes (other than Unity)
- Resolving rendering differences between Metal and OpenGL (Native only)
Compatibility
Backward compatibility and load
Enhanced Blend Shape
The loading of blend shape parameters is explained in “Enhanced blend shapes.”
Motion-sync
Motion-sync compatibility is explained in “Motion-sync.”
Fixing bugs with expression transition processing
Fixed a bug that caused unnatural animations that differed from those of the Editor when calculating blends of multiple expression parameters.
Therefore, the 5 SDK has different expression than the 4.2 SDK.
If you want to use the 4.2 SDK expression, please refer to “Fixing bugs with expression transition processing.”
Change in class structure of Renderer-related processes
For Native, for Web, and for Java, the structure of Renderer-related classes and some functions have been changed to improve maintainability of Renderer-related processing.
Replacing only the framework will result in a build error.
The specific modifications are explained in “Change in class structure of Renderer-related processes.”
Resolving rendering differences between Metal and OpenGL
For Native, a rendering difference between Metal and OpenGL has been resolved.
If you want to use the 4.2 SDK expression, please refer to “Resolving rendering differences between Metal and OpenGL”.
Update from existing 4.2 SDK and forward compatibility
- Updating from the existing 4.2 SDK to the 5.0 SDK works by replacing all files as usual.
- Please note that MOC files exported for 5 cannot be read.
- When attempting to read a MOC file exported for 5, the following error is output when calling the csmReviveMocInPlace function.
[CSM] [E]csmReviveMocInPlace is failed. The Core unsupport later than moc3 ver:[4]. This moc3 ver is [5].
Enhanced Blend Shape
Enhanced blend shape functionality has increased the number of parameters supported by blend shapes. Please refer to the table below for supported parameters and supported versions.
Blend Shape SDK Support Table
Object | Property | Supported Versions |
|---|---|---|
| Part(s) | – | 5.0 |
| Draw Order | 5.0 | |
| Warp Deformer | – | 4.2 |
| Vertices Info | 4.2 | |
| Opacity | 5.0 | |
| Multiply Color | 5.0 | |
| Screen Color | 5.0 | |
| Rotation Deformer | – | 5.0 |
| Vertex Information X | 5.0 | |
| Vertex Information Y | 5.0 | |
| Multiply Color | 5.0 | |
| Screen Color | 5.0 | |
| Angle | 5.0 | |
| Scale | 5.0 | |
| ArtMesh | – | 4.2 |
| Vertices Info | 4.2 | |
| Draw Order | 5.0 | |
| Multiply Color | 5.0 | |
| Screen Color | 5.0 | |
| Glue | – | 5.0 |
| Compatibility | 5.0 |
Changes from existing SDK and load
For backward compatibility, there are no differences in common behavior up to 4.2.
When the embedded model data version is “SDK 5.0 / Cubism 5.0 compatible”
- The properties of the Parts/ArtMesh/Warp Deformer/Rotation Deformer/Glue are exported as information for the blend shape parameters.
- As before, the values of each property are obtained from the model’s Drawable data.
The load is increased for the calculation of blend shape parameters. (Blend shapes tend to increase linearly.)
Motion-sync
Since this is a new feature, there is no explanation regarding compatibility.
Fixing bugs with expression transition processing
How to modify if 4.2 SDK expression is preferred
for Unity
With the model prefab selected, select the Use Legacy Blend Calculation check box in the CubismExpressionController from the Inspector window.
for Native
Change the type of CubismUserModel::_expressionManager and the initialization process in CubismUserModel::CubismUserModel() as follows.
https://github.com/Live2D/CubismNativeFramework/blob/develop/src/Model/CubismUserModel.hpp#L272
Code before modification
CubismExpressionMotionManager* _expressionManager; ///< Expression management
Code after modification
CubismMotionManager* _expressionManager; ///< Expression management
https://github.com/Live2D/CubismNativeFramework/blob/develop/src/Model/CubismUserModel.cpp#L42
Code before modification
_expressionManager = CSM_NEW CubismExpressionMotionManager();
Code after modification
_expressionManager = CSM_NEW CubismMotionManager();
for Web
Change the process of initializing _expressionManager in the constructor of the CubismUserModel class as follows.
https://github.com/Live2D/CubismWebFramework/blob/develop/src/model/cubismusermodel.ts#L368
Code before modification
this._expressionManager = new CubismExpressionMotionManager();
Code after modification
this._expressionManager = new CubismMotionManager();
for Java
Change the part of the definition of the expressionManager variable defined in CubismUserModel as follows.
Code before modification
protected CubismExpressionMotionManager expressionManager = new CubismExpressionMotionManager();
Code after modification
protected CubismMotionManager expressionManager = new CubismMotionManager();
Change in class structure of Renderer-related processes
For Native, for Web, and for Java, the structure of Renderer-related classes and some functions have been changed to improve maintainability of Renderer-related processing.
The specific changes are as follows:
- ClippingManager separation
- Separation of high-definition mask processing in SetupClippingContext
- Shader-related source code separation
- Moving common processing to base class
- Organizing DrawMesh arguments
- Unification of name, “OffScreen~~”
In the unlikely event that you have customized the SDK and are having difficulty updating as usual, please refer to the following changes.
ClippingManager separation
Separated ClippingManager-related processing from CubismRenderer_xx class file to CubismClippingManager class file.
For Native, the CubismClippingManager class is a common class for all Renderers.
This change improves the readability of the CubismRenderer_xx class file and the maintainability of ClippingManager-related processing.
Separation of high-definition mask processing in SetupClippingContext
Extracted high-definition mask-related processing from the CubismRenderer_xx class file, standardized it, and moved it to the CubismClippingManager class.
This change improves the readability of the CubismRenderer_xx class file and the maintainability of high-definition mask-related processing.
Shader-related source code separation
Shader-related code that was handled differently in each Renderer is now handled in the CubismShader_xx class file.
This change improves maintainability of shader-related code.
Moving common processing to base class
Processes such as matrix calculations in the CubismRenderer_xx class, which were done similarly in all derived classes, are now common because they have been moved to the base class.
This change improves the maintainability of the CubismRenderer_xx class file.
Organizing DrawMesh arguments
In Draw-related functions in the CubismRenderer_xx class, reorganized the locations where a large number of arguments needed to be set.
Since multiple member variables of the model object were set, the number of arguments was greatly reduced by setting the model object itself as an argument.
This modification improves the maintainability of Draw-related processes.
Unification of name, “OffScreen~~”
“OffScreenBuffer” and “OffScreenFrame,” which were used in several places, have been renamed to “OffScreenSurface.”
This change improves the maintainability of Renderer-related processes by using a generic designation.
Resolving rendering differences between Metal and OpenGL
For Native, a rendering difference between Metal and OpenGL has been resolved.
If you want to use the 4.2 SDK expression, please refer to CHANGELOG.md.
Cubism Core API Changes
Added definition of Cubism 5 MOC3 file return value to csmGetMocVersion function.
Please refer to the Live2D Cubism Core API Reference for more information.